Internet Application Framework Data Manipulation Language Manual

Version 8.0

IAF 8.0 DML

The information contained in this document is subject to change without notice. Except as may otherwise be provided in a written agreement with a licensee, CDC Software makes no warranty of any kind with regard to this material, either expressed or implied, including, but not limited to, the documentation, function, and performance of these programs. CDC Software disclaims all implied warranties, including, but not limited to, any implied warranty of merchantability or fitness for a particular purpose. Except as may otherwise be provided in a written agreement with a licensee, CDC Software shall not be liable for any errors contained herein or for incidental, special, or consequential damages in connection with the furnishing, performance, or use of this material, and liability for direct damages is limited to the cost of the materials. This document contains proprietary information which is protected by copyright. No part of this document may be reproduced in any manner or translated into another program language without the prior written consent of CDC Software. Copyright 2008 CDC Software Corporation. All Rights Reserved CDC Software, Ross ERP, Strategic Application Modeler (SAM) are registered trademarks of CDC Software Corporation and/or its wholly owned subsidiaries. Ross ERP, Ross APS, Ross SCM, Ross CRM, Ross EPM, Ross Localization and Customer Portal are trademarks of CDC Software Corporation and/or its wholly owned subsidiaries. Other trademarks mentioned herein are the property of their respective companies. CDC Software, Inc. Corporate Headquarters Two Concourse Parkway, Suite 800 Atlanta, Georgia 30328 (770) 351-9600

Contents
Overview IAF Data Manipulation Language Manual Purpose .................................................................................................xlii Intended Audience................................................................................xlii Related Documents ..............................................................................xlii Language Elements ............................................................................ xliii Language Statements and Constructs...................................................xlv Chapter 1 Program-Data Independence Achieving ProgramData Independence............................................1-3 Advantages of ProgramData Independence .....................................1-4 ProgramData Independence Illustration...........................................1-5 Chapter 2 Title Declarations TITLE Declaration Syntax ...................................................................2-3 Examples: ...........................................................................2-3 Chapter 3 Forms and Form Qualifiers Introduction ..........................................................................................3-4 Form Header Statement Syntax...................................................3-4 Form Arguments..........................................................................3-5 Example: .............................................................................3-5 Passing Arguments ......................................................................3-5 Examples: ...........................................................................3-5 Argument Scope ..........................................................................3-6 Example: .............................................................................3-7 Performing Forms........................................................................3-8 Return Status................................................................................3-8 Example: .............................................................................3-9 MENU Forms.....................................................................................3-10 Form Header Statement Syntax.................................................3-10 Implicit Form Actions ...............................................................3-10 Applicable Qualifiers.................................................................3-11 Example ............................................................................3-11 NORMAL Forms ...............................................................................3-12 General Purpose.........................................................................3-12 Form Header Statement Syntax.................................................3-12 Implicit Form Actions ...............................................................3-13

iii IAF 8.0 DML

Applicable Qualifiers ................................................................ 3-14 Example............................................................................ 3-14 PROCEDURE Forms ........................................................................ 3-15 General Purpose ........................................................................ 3-15 Form Header Statement Syntax ................................................ 3-15 Implicit Form Actions............................................................... 3-15 Applicable Qualifiers ................................................................ 3-16 Example:........................................................................... 3-16 QUERY Forms................................................................................... 3-17 General Purpose ........................................................................ 3-17 Form Header Statement Syntax ................................................ 3-17 Implicit Form Actions............................................................... 3-17 Applicable Qualifiers ................................................................ 3-20 Example:........................................................................... 3-21 REPORT Forms ................................................................................. 3-22 General Purpose ........................................................................ 3-22 Form Header Statement Syntax ................................................ 3-22 Implicit Form Actions............................................................... 3-22 Applicable Qualifiers ................................................................ 3-23 Example:........................................................................... 3-23 TABLE_EDIT Forms......................................................................... 3-24 General Purpose ........................................................................ 3-24 Form Header Statement Syntax ................................................ 3-24 Implicit Form Actions............................................................... 3-24 Applicable Qualifiers ................................................................ 3-28 Example............................................................................ 3-28 Form Qualifiers.................................................................................. 3-29 /ADD_FORM .................................................................................... 3-33 Syntax........................................................................................ 3-33 Description ................................................................................ 3-33 Example............................................................................ 3-33 /ALTERNATE_FORM ...................................................................... 3-34 Syntax........................................................................................ 3-34 Description ................................................................................ 3-34 Example............................................................................ 3-34 /ATTRIBUTES .................................................................................. 3-35 Syntax........................................................................................ 3-35 Description ................................................................................ 3-35 Example............................................................................ 3-35 /BASE ................................................................................................ 3-36 Syntax........................................................................................ 3-36 Description ................................................................................ 3-36 /BEGIN_ROW................................................................................... 3-37 Syntax........................................................................................ 3-37

iv IAF 8.0 DML

Description ................................................................................3-37 For REPORT forms: .........................................................3-37 For TABLE_EDIT forms:.................................................3-37 Examples...........................................................................3-37 /BREAK .............................................................................................3-38 Syntax ........................................................................................3-38 Description ................................................................................3-38 break_expression ..............................................................3-38 begin_form_name .............................................................3-38 end_form_name ................................................................3-38 break_option[,break_option[,...]]......................................3-39 Examples...........................................................................3-42 /BREAK0 ...........................................................................................3-44 Syntax ........................................................................................3-44 Description ................................................................................3-44 Examples...........................................................................3-44 /CHEADING......................................................................................3-45 Syntax ........................................................................................3-45 Description ................................................................................3-45 /COL...................................................................................................3-46 Syntax ........................................................................................3-46 Description ................................................................................3-46 Examples...........................................................................3-46 /COLUMN_HEADINGS ...................................................................3-47 Syntax ........................................................................................3-47 Description ................................................................................3-47 Example ............................................................................3-47 /COLUMN_HEADING_ROW..........................................................3-48 Syntax ........................................................................................3-48 Description ................................................................................3-48 Example ............................................................................3-48 /COLUMN_SPACING.......................................................................3-49 Syntax ........................................................................................3-49 Description ................................................................................3-49 Example ............................................................................3-49 /COMMIT_RATE ..............................................................................3-50 Syntax ........................................................................................3-50 Description ................................................................................3-50 Examples...........................................................................3-50 /DEFAULT_TAG ...............................................................................3-51 Syntax ........................................................................................3-51 Description........................................................................3-51 Example ............................................................................3-51 /DELETE_FORM ..............................................................................3-52

v IAF 8.0 DML

Syntax........................................................................................ 3-52 Description ................................................................................ 3-52 For QUERY forms: .......................................................... 3-52 For TABLE_EDIT forms: ................................................ 3-52 Example............................................................................ 3-53 /END_ROW....................................................................................... 3-54 Syntax........................................................................................ 3-54 Description ................................................................................ 3-54 For REPORT forms:......................................................... 3-54 For TABLE_EDIT forms: ................................................ 3-54 Example............................................................................ 3-54 /FIND_FORM.................................................................................... 3-55 Syntax........................................................................................ 3-55 Description ................................................................................ 3-55 For QUERY forms: .......................................................... 3-55 For REPORT forms:......................................................... 3-55 For TABLE_EDIT forms: ................................................ 3-56 Example............................................................................ 3-56 /FIRST ............................................................................................... 3-57 Syntax........................................................................................ 3-57 Description ................................................................................ 3-57 Example............................................................................ 3-57 /FOOTING......................................................................................... 3-58 Syntax........................................................................................ 3-58 Description ................................................................................ 3-58 Example............................................................................ 3-58 /FOOTING_FORM ........................................................................... 3-59 Syntax........................................................................................ 3-59 Description ................................................................................ 3-59 Examples .......................................................................... 3-59 /GROUPED_BY................................................................................ 3-61 Syntax........................................................................................ 3-61 Description ................................................................................ 3-61 Sub-group Clauses............................................................ 3-62 Examples .......................................................................... 3-64 /HEADING ........................................................................................ 3-66 Syntax........................................................................................ 3-66 Description ................................................................................ 3-66 iBrowser Note .................................................................. 3-66 Example............................................................................ 3-66 /HEADING_FORM........................................................................... 3-67 Syntax........................................................................................ 3-67 Description ................................................................................ 3-67 Example............................................................................ 3-67

vi IAF 8.0 DML

/HEIGHT............................................................................................3-68 Syntax ........................................................................................3-68 Description ................................................................................3-68 Examples...........................................................................3-68 /INPUT_ROW_HEIGHT...................................................................3-69 Syntax ........................................................................................3-69 Description ................................................................................3-69 Example ............................................................................3-69 /JOINED_TO .....................................................................................3-70 Syntax ........................................................................................3-70 Description ................................................................................3-70 Example ............................................................................3-70 /LFOOTING.......................................................................................3-71 Syntax ........................................................................................3-71 Description ................................................................................3-71 Example ............................................................................3-71 /LHEADING ......................................................................................3-72 Syntax ........................................................................................3-72 Description ................................................................................3-72 iBrowser Note ...................................................................3-72 Example ............................................................................3-72 /LINES_AFTER.................................................................................3-73 Syntax ........................................................................................3-73 Description ................................................................................3-73 Examples...........................................................................3-73 /LINES_BEFORE ..............................................................................3-74 Syntax ........................................................................................3-74 Description ................................................................................3-74 Examples..........................................................................3-74 /LOCK................................................................................................3-75 Syntax ........................................................................................3-75 Description ................................................................................3-75 Examples...........................................................................3-76 /MODIFY_FORM..............................................................................3-77 Syntax ........................................................................................3-77 Description ................................................................................3-77 Examples...........................................................................3-77 /NOERROR........................................................................................3-78 Syntax ........................................................................................3-78 Description ................................................................................3-78 Example.....................................................................................3-78 /NOEXIT_FORWARD.......................................................................3-79 Syntax ........................................................................................3-79 Description ................................................................................3-79

vii IAF 8.0 DML

/NOSTATUS ...................................................................................... 3-80 Syntax........................................................................................ 3-80 Description ................................................................................ 3-80 /OPTIONS.......................................................................................... 3-81 Syntax........................................................................................ 3-81 Description ................................................................................ 3-81 For QUERY forms: .......................................................... 3-81 For REPORT forms:......................................................... 3-82 NOTE: .............................................................................. 3-82 NOTE: .............................................................................. 3-84 INFINITE ......................................................................... 3-87 MERGED ......................................................................... 3-89 NOTE: .............................................................................. 3-89 NOUNDERLINES ........................................................... 3-92 OVERLAID ..................................................................... 3-92 NOTE: .............................................................................. 3-92 PAGE_BREAK_REPRINT.............................................. 3-95 PRINT .............................................................................. 3-97 SUMMARY ..................................................................... 3-97 ZEROSUPPRESS ............................................................ 3-99 For TABLE_EDIT forms: .............................................. 3-101 /OUTPUT......................................................................................... 3-105 Syntax...................................................................................... 3-105 Description .............................................................................. 3-105 Example.......................................................................... 3-105 /PDF ................................................................................................. 3-106 Syntax...................................................................................... 3-106 Description .............................................................................. 3-106 Options .................................................................................... 3-106 /READ_ONLY................................................................................. 3-123 Syntax...................................................................................... 3-123 Description .............................................................................. 3-123 For TABLE_EDIT forms: .............................................. 3-123 For All Forms: ................................................................ 3-123 /REDUCED_TO .............................................................................. 3-124 Syntax...................................................................................... 3-124 Description .............................................................................. 3-124 Examples ....................................................................... 3-125 /REMAIN......................................................................................... 3-127 Syntax...................................................................................... 3-127 Description .............................................................................. 3-127 Example.......................................................................... 3-128 /REPEAT.......................................................................................... 3-129 Syntax...................................................................................... 3-129

viii IAF 8.0 DML

Description ..............................................................................3-129 /RFOOTING.....................................................................................3-130 Syntax ......................................................................................3-130 Example ..........................................................................3-130 /RHEADING....................................................................................3-131 Syntax ......................................................................................3-131 Description ..............................................................................3-131 iBrowser Note .................................................................3-131 Example ..........................................................................3-131 /ROW ...............................................................................................3-132 Syntax ......................................................................................3-132 Description ..............................................................................3-132 Examples.........................................................................3-132 /ROW_HEIGHT...............................................................................3-133 Syntax ......................................................................................3-133 Description ..............................................................................3-133 Example ..........................................................................3-133 /SECONDARY.................................................................................3-134 Syntax ......................................................................................3-134 Description ..............................................................................3-134 Example ..........................................................................3-134 /SELECTION ...................................................................................3-135 Syntax ......................................................................................3-135 Description ..............................................................................3-135 Operator Precedence .......................................................3-135 Examples.........................................................................3-136 /SEQUENCE....................................................................................3-138 Syntax ......................................................................................3-138 Description ..............................................................................3-138 Example ..........................................................................3-139 /SEQUENCE_INCREMENT...........................................................3-140 Syntax ......................................................................................3-140 Description ..............................................................................3-140 Example ..........................................................................3-140 /SORTED_BY..................................................................................3-141 Syntax ......................................................................................3-141 Description ..............................................................................3-141 Examples.........................................................................3-142 /STATISTIC......................................................................................3-143 Syntax ......................................................................................3-143 Description ..............................................................................3-143 Examples.........................................................................3-145 /STATUS ..........................................................................................3-147 Syntax ......................................................................................3-147

ix IAF 8.0 DML

Description .............................................................................. 3-147 /STREAM_NAME .......................................................................... 3-149 Syntax...................................................................................... 3-149 Description .............................................................................. 3-149 Example.......................................................................... 3-149 /SYSTEM......................................................................................... 3-150 Syntax...................................................................................... 3-150 Description .............................................................................. 3-150 Examples ........................................................................ 3-150 /TABLE............................................................................................ 3-151 Syntax...................................................................................... 3-151 Description .............................................................................. 3-151 Examples ........................................................................ 3-153 /TAG_LENGTH............................................................................... 3-154 Syntax...................................................................................... 3-154 Description .............................................................................. 3-154 Examples ........................................................................ 3-154 /TITLE ............................................................................................. 3-155 Syntax...................................................................................... 3-155 Description .............................................................................. 3-155 Example.......................................................................... 3-155 /WIDTH ........................................................................................... 3-156 Syntax...................................................................................... 3-156 Description .............................................................................. 3-156 Examples ........................................................................ 3-156 /WITH.............................................................................................. 3-157 Syntax...................................................................................... 3-157 Description .............................................................................. 3-157 expression....................................................................... 3-159 Overriding Default Table Joins ...................................... 3-160 NOTE: ............................................................................ 3-161 Comparing Fields within a Table ................................... 3-161 NOTE: ............................................................................ 3-162 Missing Values ............................................................... 3-162 NOTE: ............................................................................ 3-163 Wildcard Character Matching ........................................ 3-163 NOTE: ............................................................................ 3-164 Examples ........................................................................ 3-164 Streams with a /WITH Qualifier ............................................. 3-166 Example 1:...................................................................... 3-166 Example 2:...................................................................... 3-166 Example 3:...................................................................... 3-167

x IAF 8.0 DML

Chapter 4 Fixed Display Declarations TEXT Declarations ..............................................................................4-3 Syntax ..........................................................................................4-3 text ...............................................................................................4-3 token ............................................................................................4-3 NOTE:.................................................................................4-4 /ROW=numeric_expression ...............................................4-4 /COL=numeric_expression.................................................4-4 Examples: ...........................................................................4-4 LINE Declarations................................................................................4-5 Syntax ..........................................................................................4-5 numeric_expression ............................................................4-5 /ROW=numeric_expression ...............................................4-5 /COL=numeric_expression.................................................4-5 /END_ROW=numeric_expression .....................................4-6 /END_COL=numeric_expression.......................................4-6 Examples: ...........................................................................4-6 Chapter 5 Blocks and Block Qualifiers Introduction ..........................................................................................5-4 Block Statement Syntax .......................................................................5-4 block_statement ...........................................................................5-4 block_name..................................................................................5-4 /qualifiers .....................................................................................5-4 BEGIN_BLOCK/END_BLOCK Construct.........................................5-5 Example: .............................................................................5-6 Completion Status ................................................................................5-6 DML Blocks.........................................................................................5-7 General Purpose...........................................................................5-7 Block Statement Syntax...............................................................5-7 Implicit Block Actions ................................................................5-7 Special Considerations ................................................................5-8 Qualifiers .....................................................................................5-8 Examples.............................................................................5-8 INPUT Blocks ......................................................................................5-9 General Purpose...........................................................................5-9 Block Statement Syntax...............................................................5-9 Implicit Block Actions ................................................................5-9 Special Considerations ................................................................5-9 Qualifiers ...................................................................................5-10 Example ............................................................................5-10 ITEM Blocks ......................................................................................5-11

xi IAF 8.0 DML

General Purpose ........................................................................ 5-11 Block Statement Syntax ............................................................ 5-11 Implicit Block Actions .............................................................. 5-11 Special Considerations .............................................................. 5-11 Qualifiers................................................................................... 5-12 Example............................................................................ 5-12 MENU Blocks.................................................................................... 5-13 General Purpose ........................................................................ 5-13 Block Statement Syntax ............................................................ 5-13 Implicit Block Actions .............................................................. 5-13 Special Considerations .............................................................. 5-14 Qualifiers................................................................................... 5-15 Example............................................................................ 5-15 Examples: Applying MENU Block Pulldown Menus....................... 5-16 Examples: Applying Block Button Menus ........................................ 5-18 OUTPUT Blocks................................................................................ 5-19 General Purpose ........................................................................ 5-19 Block Statement Syntax ............................................................ 5-19 Implicit Block Actions .............................................................. 5-19 Special Considerations .............................................................. 5-19 Qualifiers................................................................................... 5-20 Example............................................................................ 5-20 PAUSE Blocks ................................................................................... 5-21 General Purpose ........................................................................ 5-21 Block Statement Syntax ............................................................ 5-21 Implicit Block Actions .............................................................. 5-21 Special Considerations .............................................................. 5-21 Qualifiers................................................................................... 5-22 Example............................................................................ 5-22 SIGNATURE_BLOCK...................................................................... 5-23 General Purpose ........................................................................ 5-23 Block Statement Syntax ............................................................ 5-23 Implicit Block Actions .............................................................. 5-24 Special Considerations .............................................................. 5-24 Specific Qualifiers..................................................................... 5-24 Additional Qualifiers................................................................. 5-25 Exit Status ................................................................................. 5-26 YESNO Blocks .................................................................................. 5-27 General Purpose ........................................................................ 5-27 Block Statement Syntax ............................................................ 5-27 Implicit Block Actions .............................................................. 5-27 Special Considerations .............................................................. 5-27 Qualifiers................................................................................... 5-28 Example............................................................................ 5-28

xii IAF 8.0 DML

Examples: Applying YESNO Block Checkboxes .............................5-29 Examples: Applying YESNO Block Buttons.....................................5-30 Block Qualifiers .................................................................................5-31 /ABSOLUTE_POSITION..................................................................5-36 Syntax ........................................................................................5-36 Description ................................................................................5-36 Example ............................................................................5-36 /ATTRIBUTES...................................................................................5-37 Syntax ........................................................................................5-37 Description ................................................................................5-37 Example ............................................................................5-38 /AUDIT ..............................................................................................5-39 Syntax ........................................................................................5-39 Description ................................................................................5-39 Example ............................................................................5-39 /BACK................................................................................................5-40 Syntax ........................................................................................5-40 Description ................................................................................5-40 Examples...........................................................................5-40 /BREAK .............................................................................................5-41 Syntax ........................................................................................5-41 Description ................................................................................5-41 Example ...........................................................................5-41 /CHEADING......................................................................................5-42 Syntax ........................................................................................5-42 Description ................................................................................5-42 Example ............................................................................5-42 /COL...................................................................................................5-43 Syntax ........................................................................................5-43 Description ................................................................................5-43 /COL=keyword .................................................................5-44 Examples...........................................................................5-44 /DATETIME.......................................................................................5-45 Syntax ........................................................................................5-45 Description ................................................................................5-45 Example ............................................................................5-45 /DISPLAY_LENGTH.........................................................................5-46 Syntax ........................................................................................5-46 Description ................................................................................5-46 Example ............................................................................5-46 /DISPLAY_ONLY..............................................................................5-47 Syntax ........................................................................................5-47 Description ................................................................................5-47 Example ............................................................................5-47

xiii IAF 8.0 DML

/DOMAIN.......................................................................................... 5-48 Syntax........................................................................................ 5-48 Description ................................................................................ 5-48 Output Block Domain Validation ..................................... 5-49 Examples .......................................................................... 5-49 /DOUBLE .......................................................................................... 5-50 Syntax........................................................................................ 5-50 Description ................................................................................ 5-50 /ERASE.............................................................................................. 5-51 /EXIT ................................................................................................. 5-52 Syntax........................................................................................ 5-52 Description ................................................................................ 5-52 Examples .......................................................................... 5-52 /EXIT_FORWARD............................................................................ 5-53 Syntax........................................................................................ 5-53 Description ................................................................................ 5-53 Example............................................................................ 5-54 /FACILITY ........................................................................................ 5-55 Syntax........................................................................................ 5-55 Description ................................................................................ 5-55 /FAILURE.......................................................................................... 5-56 Syntax........................................................................................ 5-56 Description ................................................................................ 5-56 Example............................................................................ 5-56 /HEADING ........................................................................................ 5-57 Syntax........................................................................................ 5-57 Description ................................................................................ 5-57 Example............................................................................ 5-57 /HEIGHT ........................................................................................... 5-58 Syntax........................................................................................ 5-58 Description ................................................................................ 5-58 For input blocks:............................................................... 5-58 For output blocks:............................................................. 5-58 For menu blocks: .............................................................. 5-60 Example............................................................................ 5-60 /INPUT_MASK ................................................................................. 5-61 Syntax........................................................................................ 5-61 Description ................................................................................ 5-61 Example............................................................................ 5-61 /ITEM................................................................................................. 5-62 Syntax........................................................................................ 5-62 Description ................................................................................ 5-62 Examples .......................................................................... 5-62 /ITEM_IF ........................................................................................... 5-63

xiv IAF 8.0 DML

Syntax ........................................................................................5-63 Description ................................................................................5-63 Example ............................................................................5-63 /LEN ...................................................................................................5-64 Syntax ........................................................................................5-64 Description ................................................................................5-64 Examples...........................................................................5-67 /LHEADING ......................................................................................5-68 Syntax ........................................................................................5-68 Description ................................................................................5-68 Example.....................................................................................5-68 /LOV...................................................................................................5-69 Syntax ........................................................................................5-69 Description........................................................................5-69 Example ............................................................................5-69 /LOV_AUTO_SELECT.....................................................................5-70 Syntax ........................................................................................5-70 Description ................................................................................5-70 Example ............................................................................5-70 /LOV_COL.........................................................................................5-71 Syntax ........................................................................................5-71 Description ................................................................................5-71 Examples...........................................................................5-71 /LOV_DATA ......................................................................................5-72 Syntax ........................................................................................5-72 Description ................................................................................5-72 Example ............................................................................5-72 /LOV_FIRST......................................................................................5-73 Syntax ........................................................................................5-73 Description ................................................................................5-73 Example ............................................................................5-73 /LOV_HEIGHT..................................................................................5-74 Syntax ........................................................................................5-74 Description ................................................................................5-74 Example ............................................................................5-74 /LOV_NOHEADING.........................................................................5-75 Syntax ........................................................................................5-75 Description ................................................................................5-75 /LOV_NOSEARCH ...........................................................................5-76 Syntax ........................................................................................5-76 Description ................................................................................5-76 Example ............................................................................5-76 /LOV_REDUCED_TO ......................................................................5-77 Syntax ........................................................................................5-77

xv IAF 8.0 DML

Description ................................................................................ 5-77 Example............................................................................ 5-77 /LOV_ROW....................................................................................... 5-78 Syntax........................................................................................ 5-78 Description ................................................................................ 5-78 Examples .......................................................................... 5-78 /LOV_SECONDARY........................................................................ 5-79 Syntax........................................................................................ 5-79 Description ................................................................................ 5-79 /LOV_SELECTION .......................................................................... 5-80 Syntax........................................................................................ 5-80 Description ................................................................................ 5-80 Operator Precedence......................................................... 5-81 Examples .......................................................................... 5-82 /LOV_SORTED_BY ......................................................................... 5-83 Syntax........................................................................................ 5-83 Description ................................................................................ 5-83 Example............................................................................ 5-83 /LOV_WIDTH................................................................................... 5-84 Syntax........................................................................................ 5-84 Description ................................................................................ 5-84 Example............................................................................ 5-84 /LOV_WITH...................................................................................... 5-85 Syntax........................................................................................ 5-85 Description ................................................................................ 5-85 field_name ........................................................................ 5-85 operator............................................................................. 5-85 value_expression .............................................................. 5-87 Examples .......................................................................... 5-87 /NEW ................................................................................................. 5-88 Syntax........................................................................................ 5-88 Description ................................................................................ 5-88 Using /NEW with /PROTECT ......................................... 5-88 Example............................................................................ 5-89 /NOAUDIT ........................................................................................ 5-90 Syntax........................................................................................ 5-90 Description ................................................................................ 5-90 Example............................................................................ 5-90 /NOCLEAR_BUFFER ...................................................................... 5-91 Syntax........................................................................................ 5-91 Description ................................................................................ 5-91 /NODOMAIN .................................................................................... 5-92 Syntax........................................................................................ 5-92 Description ................................................................................ 5-92

xvi IAF 8.0 DML

/NOLOV_DATA ................................................................................5-93 Syntax ........................................................................................5-93 Description ................................................................................5-93 Example ............................................................................5-93 /NOHEADING...................................................................................5-93 Syntax ........................................................................................5-93 Description ................................................................................5-93 /NOREPEAT ......................................................................................5-94 Syntax ........................................................................................5-94 Description ................................................................................5-94 /NOUNDERLINES............................................................................5-94 Syntax ........................................................................................5-94 Description ................................................................................5-94 /OPT ...................................................................................................5-95 Syntax ........................................................................................5-95 Description ................................................................................5-95 /OPTIONS ..........................................................................................5-96 Syntax ........................................................................................5-96 Description ................................................................................5-96 /OUTPUT_MASK .............................................................................5-97 Syntax ........................................................................................5-97 Description ................................................................................5-97 Examples...........................................................................5-97 /PDF ...................................................................................................5-98 Syntax ........................................................................................5-98 Description ................................................................................5-98 Options ......................................................................................5-98 Examples...........................................................................5-99 /PROMPT .........................................................................................5-101 Syntax ......................................................................................5-101 Description ..............................................................................5-101 Examples.........................................................................5-102 /PROTECT .......................................................................................5-103 Syntax ......................................................................................5-103 Description ..............................................................................5-103 Using /PROTECT with /NEW........................................5-103 Example ..........................................................................5-104 /PURPOSE .......................................................................................5-105 Syntax ......................................................................................5-105 Description ..............................................................................5-105 Example ..........................................................................5-105 /RECALL .........................................................................................5-106 /RHEADING....................................................................................5-107 Syntax ......................................................................................5-107

xvii IAF 8.0 DML

Description .............................................................................. 5-107 Example.......................................................................... 5-107 /ROW ............................................................................................... 5-108 Syntax...................................................................................... 5-108 Description .............................................................................. 5-108 Example.......................................................................... 5-108 /SAVE .............................................................................................. 5-109 /SOURCE......................................................................................... 5-110 Syntax...................................................................................... 5-110 Description .............................................................................. 5-110 Examples ........................................................................ 5-111 /SOURCE_IF ................................................................................... 5-112 Syntax...................................................................................... 5-112 Description .............................................................................. 5-112 Examples ........................................................................ 5-113 /SUCCESS ....................................................................................... 5-115 Syntax...................................................................................... 5-115 Description .............................................................................. 5-115 Example .................................................................................. 5-115 /TAG ................................................................................................ 5-116 Syntax...................................................................................... 5-116 Description .............................................................................. 5-116 Example.......................................................................... 5-116 /TAG_LENGTH............................................................................... 5-117 Syntax...................................................................................... 5-117 Description .............................................................................. 5-117 Examples ........................................................................ 5-117 /TARGET......................................................................................... 5-118 Syntax...................................................................................... 5-118 Description .............................................................................. 5-118 Examples ........................................................................ 5-119 /TITLE ............................................................................................. 5-120 Syntax...................................................................................... 5-120 Description .............................................................................. 5-120 Example.......................................................................... 5-120 /TOTAL............................................................................................ 5-121 Syntax...................................................................................... 5-121 Description .............................................................................. 5-121 Example.......................................................................... 5-122 /USE_IF ........................................................................................... 5-123 Syntax...................................................................................... 5-123 Description .............................................................................. 5-123 Examples ........................................................................ 5-123 /USERNAME1 ................................................................................ 5-124

xviii IAF 8.0 DML

Syntax ......................................................................................5-124 Description ..............................................................................5-124 Example ..........................................................................5-124 /USERNAME2.................................................................................5-125 Syntax ......................................................................................5-125 Description ..............................................................................5-125 Example...................................................................................5-125 /USER1-5 .........................................................................................5-126 Syntax ......................................................................................5-126 Description ..............................................................................5-126 Example ..........................................................................5-126 /USER_KEYn ..................................................................................5-127 Syntax ......................................................................................5-127 Description ..............................................................................5-127 Examples.........................................................................5-127 /USING.............................................................................................5-128 Syntax ......................................................................................5-128 Description ..............................................................................5-128 For input blocks: .............................................................5-128 For output blocks: ...........................................................5-130 Examples.........................................................................5-130 /VALIDATION.................................................................................5-131 Syntax ......................................................................................5-131 Description ..............................................................................5-131 Example ..........................................................................5-131 Chapter 6 Language Statements Language Statements Table..................................................................6-3 ADD ADMIN_ID ..............................................................................6-21 Syntax ........................................................................................6-21 Category ....................................................................................6-21 Description ................................................................................6-21 Example.....................................................................................6-21 ADD ROLE........................................................................................6-22 Syntax ........................................................................................6-22 Category ....................................................................................6-22 Description ................................................................................6-22 Examples ...................................................................................6-23 ADD ROLE_USER............................................................................6-24 Syntax ........................................................................................6-24 Category ....................................................................................6-24 Description ................................................................................6-24 Example.....................................................................................6-24

xix IAF 8.0 DML

ADD TO ............................................................................................ 6-25 Syntax........................................................................................ 6-25 Category .................................................................................... 6-25 Description ................................................................................ 6-25 Example............................................................................ 6-26 Related Topics .................................................................. 6-26 Qualifiers................................................................................... 6-27 ADD USER_ROLE ........................................................................... 6-28 Syntax........................................................................................ 6-28 Category .................................................................................... 6-28 Description ................................................................................ 6-28 Example .................................................................................... 6-28 Archive............................................................................................... 6-29 Syntax........................................................................................ 6-29 Category .................................................................................... 6-29 Description ................................................................................ 6-29 Qualifiers................................................................................... 6-30 ASSERT............................................................................................. 6-31 Syntax........................................................................................ 6-31 Category .................................................................................... 6-31 Description ................................................................................ 6-31 Qualifiers................................................................................... 6-31 Example 1......................................................................... 6-31 Related Topics .................................................................. 6-32 ASSERT_EQUAL ............................................................................. 6-33 Syntax........................................................................................ 6-33 Category .................................................................................... 6-33 Description ................................................................................ 6-33 Qualifiers................................................................................... 6-33 Example 1......................................................................... 6-33 Example 2......................................................................... 6-34 Related Topics .................................................................. 6-34 ASSERT_FAIL .................................................................................. 6-35 Syntax........................................................................................ 6-35 Category .................................................................................... 6-35 Description ................................................................................ 6-35 Qualifiers................................................................................... 6-35 Example............................................................................ 6-35 Related Topics .................................................................. 6-36 BEGIN_DISABLE_TRIGGER ......................................................... 6-37 Syntax........................................................................................ 6-37 Category .................................................................................... 6-37 Description ................................................................................ 6-37 Example............................................................................ 6-37

xx IAF 8.0 DML

Related Topics...................................................................6-37 BEGIN_SIGNAL_TO_STATUS .......................................................6-38 Syntax ........................................................................................6-38 Category ....................................................................................6-38 Description ................................................................................6-38 Example ............................................................................6-39 Related Topics...................................................................6-39 CALL .................................................................................................6-40 Syntax ........................................................................................6-40 Category ....................................................................................6-40 Description........................................................................6-40 Examples...........................................................................6-41 Related Topics...................................................................6-41 CALL_WEB_SERVICE ....................................................................6-42 Syntax ........................................................................................6-42 Category ....................................................................................6-42 Description ................................................................................6-42 Qualifiers ...................................................................................6-42 Examples ...................................................................................6-43 CASE, BEGIN_CASE, CASE ELSE, and END_CASE ...................6-44 Syntax ........................................................................................6-44 Category ....................................................................................6-44 Description ................................................................................6-44 Example ............................................................................6-46 Related Topics...................................................................6-47 CD ......................................................................................................6-48 Syntax ........................................................................................6-48 Category ....................................................................................6-48 Description ................................................................................6-48 CHECK_DOMAIN............................................................................6-49 Syntax ........................................................................................6-49 Category ....................................................................................6-49 Description ................................................................................6-49 Qualifiers ...................................................................................6-51 Examples...........................................................................6-55 Related Topics...................................................................6-56 CLEAR_ARRAY ...............................................................................6-57 Syntax ........................................................................................6-57 Category ....................................................................................6-57 Description ................................................................................6-57 Examples ...................................................................................6-57 CLEAR_BUFFER..............................................................................6-58 Syntax ........................................................................................6-58 Category ....................................................................................6-58

xxi IAF 8.0 DML

Description ....................................................................... 6-58 Examples .......................................................................... 6-59 Related Topics .................................................................. 6-59 CLI ..................................................................................................... 6-60 Syntax........................................................................................ 6-60 Category .................................................................................... 6-60 Description ................................................................................ 6-60 Qualifiers................................................................................... 6-60 Related Topics .................................................................. 6-61 CLOSE............................................................................................... 6-62 Syntax........................................................................................ 6-62 Category .................................................................................... 6-62 Description ................................................................................ 6-62 Examples .......................................................................... 6-62 Related Topics .................................................................. 6-62 CLOSE_TABS................................................................................... 6-63 Syntax........................................................................................ 6-63 Optional Qualifiers.................................................................... 6-63 Description ................................................................................ 6-63 Corresponding UIDL ................................................................ 6-63 Description ................................................................................ 6-63 Attributes................................................................................... 6-64 Syntax........................................................................................ 6-64 CLOSE_TEXT................................................................................... 6-65 Syntax........................................................................................ 6-65 Category .................................................................................... 6-65 Description ................................................................................ 6-65 Examples .......................................................................... 6-65 Related Topics .................................................................. 6-65 COCALL ........................................................................................... 6-66 Syntax........................................................................................ 6-66 Category .................................................................................... 6-66 Description ................................................................................ 6-66 Example 1......................................................................... 6-68 Example 2......................................................................... 6-68 Example 3......................................................................... 6-69 Example 4......................................................................... 6-69 Example 5......................................................................... 6-69 Example 6......................................................................... 6-70 Example 7......................................................................... 6-70 Example 8......................................................................... 6-71 Example 9......................................................................... 6-72 Example 10....................................................................... 6-73 COCREATE....................................................................................... 6-74

xxii IAF 8.0 DML

Syntax ........................................................................................6-74 Category ....................................................................................6-74 Description ................................................................................6-74 Example 1 .........................................................................6-77 COM Special Parameter Considerations.......................................6-80 COM Success ............................................................................6-80 COM Warning ...........................................................................6-80 COM Error.................................................................................6-80 Advanced Usage Notes..............................................................6-80 Accessing Windows Server from a remote PC..........................6-80 Running Thin Client/Server on the same PC ............................6-81 Third Party COM Objects .........................................................6-81 COMMIT ...........................................................................................6-82 Syntax ........................................................................................6-82 Category ....................................................................................6-82 Description ................................................................................6-82 Related Topics...................................................................6-83 COMPILE ..........................................................................................6-84 Syntax ........................................................................................6-84 Category ....................................................................................6-84 Description ................................................................................6-84 Qualifiers ...................................................................................6-85 Example ............................................................................6-86 Related Topics...................................................................6-86 CONNECT .........................................................................................6-87 Syntax ........................................................................................6-87 Category ....................................................................................6-87 Description ................................................................................6-87 Parameters .................................................................................6-88 Examples ...................................................................................6-88 Related Topics ...........................................................................6-88 CONTINUE .......................................................................................6-89 Syntax ........................................................................................6-89 Category ....................................................................................6-89 Description ................................................................................6-89 Keywords...................................................................................6-89 Example ............................................................................6-90 Related Topics...................................................................6-90 COPY_FILE.......................................................................................6-91 Syntax ........................................................................................6-91 Description ................................................................................6-91 Parameters.........................................................................6-91 Qualifiers ...................................................................................6-92 Example ............................................................................6-92

xxiii IAF 8.0 DML

CORELEASE .................................................................................... 6-93 Syntax........................................................................................ 6-93 Category .................................................................................... 6-93 Description ................................................................................ 6-93 Example 1......................................................................... 6-93 Example 2......................................................................... 6-94 Example 3......................................................................... 6-95 Example 4....................................................................... 6-100 Example 5....................................................................... 6-102 CPANEL .......................................................................................... 6-105 Introduction............................................................................. 6-105 Syntax...................................................................................... 6-105 Description .............................................................................. 6-105 Qualifiers................................................................................. 6-105 Examples ........................................................................ 6-107 CROSS_REFERENCE.................................................................... 6-108 Syntax...................................................................................... 6-108 Category .................................................................................. 6-108 Description .............................................................................. 6-108 Related Topics ................................................................ 6-109 DCL ................................................................................................. 6-110 Syntax...................................................................................... 6-110 Category .................................................................................. 6-110 Description .............................................................................. 6-110 Related Topics ................................................................ 6-110 DELETE ADMIN_IDS ................................................................... 6-111 Syntax...................................................................................... 6-111 Category .................................................................................. 6-111 Description .............................................................................. 6-111 Examples................................................................................. 6-111 DELETE FROM .............................................................................. 6-112 Syntax...................................................................................... 6-112 Category .................................................................................. 6-112 Description .............................................................................. 6-112 Domain and Trigger Considerations ....................................... 6-113 Qualifier .................................................................................. 6-114 Examples ....................................................................... 6-114 Related Topics ................................................................ 6-114 DELETE ROLES............................................................................. 6-115 Syntax...................................................................................... 6-115 Category .................................................................................. 6-115 Description .............................................................................. 6-115 Examples................................................................................. 6-115 DELETE ROLE_USER................................................................... 6-116

xxiv IAF 8.0 DML

Syntax ......................................................................................6-116 Category ..................................................................................6-116 Description ..............................................................................6-116 Example...................................................................................6-116 DELETE USER_ROLE ...................................................................6-117 Syntax ......................................................................................6-117 Category ..................................................................................6-117 Description ..............................................................................6-117 Examples .................................................................................6-117 DIR ...................................................................................................6-118 Syntax ......................................................................................6-118 Category ..................................................................................6-118 Description ..............................................................................6-118 Example ..........................................................................6-118 Related Topics.................................................................6-118 DISCONNECT.................................................................................6-119 Syntax ......................................................................................6-119 Category ..................................................................................6-119 Description ..............................................................................6-119 Parameters ...............................................................................6-119 Examples .................................................................................6-119 Related Topics .........................................................................6-119 DISPLAY .........................................................................................6-121 Syntax ......................................................................................6-121 Category ..................................................................................6-121 Description ..............................................................................6-121 Keywords.................................................................................6-121 Example ..........................................................................6-123 Related Topics.................................................................6-123 DOCUMENTATION........................................................................6-124 Syntax ......................................................................................6-124 Category ..................................................................................6-124 Description ..............................................................................6-124 Example ..........................................................................6-124 Related Topics.................................................................6-124 EDIT.................................................................................................6-125 Syntax ......................................................................................6-125 Category ..................................................................................6-125 Description ..............................................................................6-125 Examples.........................................................................6-125 Related Topics.................................................................6-125 EDIT/DICTIONARY .......................................................................6-126 Syntax ......................................................................................6-126 Category ..................................................................................6-126

xxv IAF 8.0 DML

Description .............................................................................. 6-126 Related Topics ................................................................ 6-126 EDIT/FORMS.................................................................................. 6-127 Syntax...................................................................................... 6-127 Category .................................................................................. 6-127 Description .............................................................................. 6-127 Examples ........................................................................ 6-127 Related Topics ................................................................ 6-127 EDIT/REPORTS.............................................................................. 6-128 Syntax...................................................................................... 6-128 Category .................................................................................. 6-128 Description .............................................................................. 6-128 Examples ........................................................................ 6-128 Related Topics ................................................................ 6-128 EDIT/SECURITY............................................................................ 6-129 Syntax...................................................................................... 6-129 Category .................................................................................. 6-129 Description .............................................................................. 6-129 Related Topics ................................................................ 6-129 EDIT/SYSTEM ............................................................................... 6-130 Syntax...................................................................................... 6-130 Category .................................................................................. 6-130 Description .............................................................................. 6-130 Related Topics ................................................................ 6-130 EDIT/TABLE................................................................................... 6-131 Syntax...................................................................................... 6-131 Category .................................................................................. 6-131 Description .............................................................................. 6-131 Qualifier .................................................................................. 6-132 Examples ........................................................................ 6-132 Examples ........................................................................ 6-132 Related Topics ................................................................ 6-132 END_DISABLE_TRIGGER ........................................................... 6-133 Syntax...................................................................................... 6-133 Category .................................................................................. 6-133 Description .............................................................................. 6-133 Example.......................................................................... 6-133 Related Topics ................................................................ 6-133 END_EXECUTE ............................................................................. 6-134 Syntax...................................................................................... 6-134 Description .............................................................................. 6-134 Qualifiers................................................................................. 6-134 Parameters ............................................................................... 6-134 Examples ........................................................................ 6-135

xxvi IAF 8.0 DML

Related Topics.................................................................6-135 END_EXECUTE .............................................................................6-136 Syntax ......................................................................................6-136 Category ..................................................................................6-136 Description ..............................................................................6-136 Qualifiers .................................................................................6-136 Parameters ...............................................................................6-136 Examples .................................................................................6-137 Related Topics .........................................................................6-137 END_GTID ......................................................................................6-138 Syntax ......................................................................................6-138 Category ..................................................................................6-138 Description ..............................................................................6-138 Related Topics .........................................................................6-138 END_SIGNAL_TO_STATUS .........................................................6-140 Syntax ......................................................................................6-140 Category ..................................................................................6-140 Description ..............................................................................6-140 Example ..........................................................................6-140 Related Topics.................................................................6-140 ERASE .............................................................................................6-141 Syntax ......................................................................................6-141 Category ..................................................................................6-141 Description ..............................................................................6-141 Qualifiers .................................................................................6-141 Examples.........................................................................6-141 ERROR.............................................................................................6-143 Syntax ......................................................................................6-143 Category ..................................................................................6-143 Description ..............................................................................6-143 ERROR_TEXT ................................................................................6-144 Syntax ......................................................................................6-144 Category ..................................................................................6-144 Description ..............................................................................6-144 Qualifiers .................................................................................6-145 Examples.........................................................................6-146 Related Topics.................................................................6-146 EXECUTE........................................................................................6-147 Syntax ......................................................................................6-147 Category ..................................................................................6-147 Description ..............................................................................6-147 Qualifiers .................................................................................6-147 Parameters ...............................................................................6-148 Examples .................................................................................6-149

xxvii IAF 8.0 DML

Related Topics......................................................................... 6-149 EXIT ................................................................................................ 6-150 Syntax...................................................................................... 6-150 Category .................................................................................. 6-150 Description .............................................................................. 6-150 Examples ........................................................................ 6-151 Related Topics ................................................................ 6-151 EXPORT .......................................................................................... 6-152 Syntax...................................................................................... 6-152 Category .................................................................................. 6-152 Description .............................................................................. 6-152 Implicit Actions....................................................................... 6-153 Special Considerations ............................................................ 6-153 Qualifiers................................................................................. 6-156 Exit Status ............................................................................... 6-161 EXPORT/CSV ................................................................................. 6-162 Syntax...................................................................................... 6-162 Category .................................................................................. 6-162 Description .............................................................................. 6-162 Implicit Actions....................................................................... 6-162 Qualifiers................................................................................. 6-163 Exit Status ............................................................................... 6-168 EXPORT/XML ................................................................................ 6-169 Syntax...................................................................................... 6-169 Category .................................................................................. 6-169 Description .............................................................................. 6-169 Qualifiers................................................................................. 6-169 Related Topics......................................................................... 6-170 EXTERNAL .................................................................................... 6-171 Syntax...................................................................................... 6-171 Category .................................................................................. 6-171 Description .............................................................................. 6-171 Examples ........................................................................ 6-173 Related Topics ................................................................ 6-173 FETCH............................................................................................. 6-175 Syntax...................................................................................... 6-175 Category .................................................................................. 6-175 Description .............................................................................. 6-175 Qualifiers ........................................................................ 6-175 Examples ........................................................................ 6-176 Related Topics ................................................................ 6-176 FILES............................................................................................... 6-177 Syntax...................................................................................... 6-177 Category .................................................................................. 6-177

xxviii IAF 8.0 DML

Description ..............................................................................6-177 Qualifiers .................................................................................6-178 Examples.........................................................................6-186 Related Topics.................................................................6-186 FIND IN ...........................................................................................6-187 Syntax ......................................................................................6-187 Category ..................................................................................6-187 Description ..............................................................................6-187 Qualifiers .................................................................................6-188 Examples.........................................................................6-190 Related Topics.................................................................6-191 FINISH .............................................................................................6-192 Syntax ......................................................................................6-192 Category ..................................................................................6-192 Description ..............................................................................6-192 Parameters ...............................................................................6-192 Examples .................................................................................6-192 Related Topics .........................................................................6-192 FLOW_BLOCK ...............................................................................6-194 Syntax ......................................................................................6-194 Description ..............................................................................6-194 Flow and Menu Blocks............................................................6-194 Syntax .............................................................................6-194 FLOW_CONNECTOR ....................................................................6-195 Syntax ......................................................................................6-195 Description ..............................................................................6-195 Required Qualifiers .................................................................6-195 Optional Qualifiers ..................................................................6-195 FLOW_NODE .................................................................................6-196 Syntax ......................................................................................6-196 Description ..............................................................................6-196 Required qualifiers ..................................................................6-196 Optional Qualifiers ..................................................................6-196 GENERATE/FORMS.......................................................................6-198 Syntax ......................................................................................6-198 Category ..................................................................................6-198 Description ..............................................................................6-198 Related Topics .........................................................................6-198 GENERATE/REPORTS...................................................................6-199 Syntax ......................................................................................6-199 Category ..................................................................................6-199 Description ..............................................................................6-199 Related Topics.................................................................6-199 GOTO...............................................................................................6-200

xxix IAF 8.0 DML

Syntax...................................................................................... 6-200 Category .................................................................................. 6-200 Description .............................................................................. 6-200 Examples ........................................................................ 6-200 Related Topics ................................................................ 6-200 IF, ELSE_IF, ELSE, and END_IF ................................................... 6-201 Syntax...................................................................................... 6-201 Category .................................................................................. 6-201 Description .............................................................................. 6-202 Examples ........................................................................ 6-203 Related Topics ................................................................ 6-203 IMPORT........................................................................................... 6-204 Syntax...................................................................................... 6-204 Category .................................................................................. 6-204 Description .............................................................................. 6-204 Implicit Actions....................................................................... 6-205 Special Considerations ............................................................ 6-205 Qualifiers................................................................................. 6-207 Exit Status ............................................................................... 6-211 IMPORT/CSV.................................................................................. 6-212 Syntax...................................................................................... 6-212 Category .................................................................................. 6-212 Description .............................................................................. 6-212 Implicit Actions....................................................................... 6-212 Qualifiers................................................................................. 6-213 Exit Status ............................................................................... 6-217 IMPORT/XML................................................................................. 6-219 Syntax...................................................................................... 6-219 Description .............................................................................. 6-219 Qualifiers................................................................................. 6-219 Related Topics......................................................................... 6-221 INVOKE .......................................................................................... 6-222 Syntax...................................................................................... 6-222 Category .................................................................................. 6-222 Description .............................................................................. 6-222 Qualifiers................................................................................. 6-224 Examples: ....................................................................... 6-224 Metadata Batching .................................................................. 6-225 Migrating to IAF 6.1 ............................................................... 6-226 Example:......................................................................... 6-226 Related Topics ................................................................ 6-228 LICENSE ......................................................................................... 6-229 Syntax...................................................................................... 6-229 Category .................................................................................. 6-229

xxx IAF 8.0 DML

Description ..............................................................................6-229 LOAD...............................................................................................6-230 Syntax ......................................................................................6-230 Category ..................................................................................6-230 Description ..............................................................................6-230 Examples.........................................................................6-230 Related Topics.................................................................6-230 LOG..................................................................................................6-232 Syntax ......................................................................................6-232 Category ..................................................................................6-232 Description ..............................................................................6-232 Example 1 .......................................................................6-232 Example 2 .......................................................................6-232 Related Topics.................................................................6-233 MAIL................................................................................................6-234 Syntax ......................................................................................6-234 Category ..................................................................................6-234 Description ..............................................................................6-234 Qualifiers .................................................................................6-234 Examples.........................................................................6-235 Related Topics.................................................................6-235 MAIL/SMTP ....................................................................................6-236 Syntax ......................................................................................6-236 Category ..................................................................................6-236 Description ..............................................................................6-237 Qualifiers .................................................................................6-237 Examples.........................................................................6-245 Client Authentication......................................................6-245 Mailbox Address Specification Format ..........................6-246 Message Format..............................................................6-246 Related System Customization Variables .......................6-247 SMTP Server Feature Determination .............................6-250 GEMTRACE Logging....................................................6-252 MENU ..............................................................................................6-253 Syntax ......................................................................................6-253 Category ..................................................................................6-253 Description ..............................................................................6-253 Example ..........................................................................6-253 Related Topics.................................................................6-254 MESSAGE .......................................................................................6-255 Syntax ......................................................................................6-255 Category ..................................................................................6-255 Description ..............................................................................6-255 Qualifiers .................................................................................6-256

xxxi IAF 8.0 DML

Examples ........................................................................ 6-256 Related Topics ................................................................ 6-257 MODIFY FACILITY....................................................................... 6-258 Syntax...................................................................................... 6-258 Category .................................................................................. 6-258 Description .............................................................................. 6-258 Qualifiers................................................................................. 6-258 Example .................................................................................. 6-258 MODIFY ROLE .............................................................................. 6-259 Syntax...................................................................................... 6-259 Category .................................................................................. 6-259 Description .............................................................................. 6-259 Example .................................................................................. 6-260 OPEN ............................................................................................... 6-261 Syntax...................................................................................... 6-261 Category .................................................................................. 6-261 Description .............................................................................. 6-261 Qualifiers................................................................................. 6-261 Example.......................................................................... 6-262 Related Topics ................................................................ 6-262 OPEN_APPLICATION ................................................................... 6-263 Syntax...................................................................................... 6-263 Category .................................................................................. 6-263 Description .............................................................................. 6-263 Parameters ............................................................................... 6-263 Examples................................................................................. 6-264 OPEN_TAB ..................................................................................... 6-265 Syntax...................................................................................... 6-265 Category .................................................................................. 6-265 Description .............................................................................. 6-265 Qualifiers................................................................................. 6-265 OPEN_TEXT................................................................................... 6-267 Syntax...................................................................................... 6-267 Category .................................................................................. 6-267 Description .............................................................................. 6-267 Qualifiers................................................................................. 6-267 Example.......................................................................... 6-268 Related Topics ................................................................ 6-268 OPEN_URL ..................................................................................... 6-269 Syntax...................................................................................... 6-269 Description .............................................................................. 6-269 PERFORM....................................................................................... 6-270 Syntax...................................................................................... 6-270 Category .................................................................................. 6-270

xxxii IAF 8.0 DML

Description ..............................................................................6-270 Qualifiers .................................................................................6-272 Examples.........................................................................6-275 Related Topics.................................................................6-276 PWD .................................................................................................6-278 Syntax ......................................................................................6-278 Category ..................................................................................6-278 Description ..............................................................................6-278 PRINT ..............................................................................................6-279 Syntax ......................................................................................6-279 Category ..................................................................................6-279 Description ..............................................................................6-279 Qualifiers .................................................................................6-279 Examples.........................................................................6-280 Related Topics.................................................................6-280 QUERY ............................................................................................6-281 Syntax ......................................................................................6-281 Category ..................................................................................6-281 Description ..............................................................................6-281 Qualifier...................................................................................6-282 Examples.........................................................................6-282 Related Topics.................................................................6-282 RANDOMIZE..................................................................................6-283 Syntax ......................................................................................6-283 Category ..................................................................................6-283 Description ..............................................................................6-283 READ_LINE....................................................................................6-284 Syntax ......................................................................................6-284 Category ..................................................................................6-284 Description ..............................................................................6-284 Qualifier...................................................................................6-284 Examples.........................................................................6-284 Related Topics.................................................................6-285 RECEIVE .........................................................................................6-286 Syntax ......................................................................................6-286 Category ..................................................................................6-286 Description ..............................................................................6-286 Qualifiers .................................................................................6-286 Examples.........................................................................6-287 Related Topics.................................................................6-287 RECEIVE_DATA.............................................................................6-288 Syntax ......................................................................................6-288 Category ..................................................................................6-288 Description ..............................................................................6-288

xxxiii IAF 8.0 DML

Qualifiers................................................................................. 6-289 Parameters ............................................................................... 6-289 Example .................................................................................. 6-289 Related Topics......................................................................... 6-289 RECEIVE_TABLE .......................................................................... 6-291 Syntax...................................................................................... 6-291 Category .................................................................................. 6-291 Description .............................................................................. 6-291 Qualifiers................................................................................. 6-292 Examples................................................................................. 6-292 Related Topics......................................................................... 6-292 RELEASE........................................................................................ 6-294 Syntax...................................................................................... 6-294 Category .................................................................................. 6-294 Description .............................................................................. 6-294 Example.......................................................................... 6-294 Related Topics ................................................................ 6-294 REPORT .......................................................................................... 6-295 Syntax...................................................................................... 6-295 Category .................................................................................. 6-295 Description .............................................................................. 6-295 Related Topics ................................................................ 6-295 REPOSITION .................................................................................. 6-296 Syntax...................................................................................... 6-296 Category .................................................................................. 6-296 Description .............................................................................. 6-296 Examples ........................................................................ 6-296 Related Topics ................................................................ 6-297 REWIND_TEXT ............................................................................. 6-298 Syntax...................................................................................... 6-298 Category .................................................................................. 6-298 Description .............................................................................. 6-298 Examples ........................................................................ 6-298 Related Topics ................................................................ 6-298 ROLLBACK.................................................................................... 6-299 Syntax...................................................................................... 6-299 Category .................................................................................. 6-299 Description .............................................................................. 6-299 Related Topics ................................................................ 6-299 RUN_TESTS ................................................................................... 6-301 Syntax...................................................................................... 6-301 Category .................................................................................. 6-301 Description .............................................................................. 6-301 Example 1....................................................................... 6-302

xxxiv IAF 8.0 DML

Example 2 .......................................................................6-303 Related Topics.................................................................6-305 SEARCH ..........................................................................................6-306 Syntax ......................................................................................6-306 Category ..................................................................................6-306 Description ..............................................................................6-306 Examples.........................................................................6-306 Related Topics.................................................................6-307 SEND ...............................................................................................6-308 Syntax ......................................................................................6-308 Category ..................................................................................6-308 Description ..............................................................................6-308 Qualifiers .................................................................................6-309 Examples.........................................................................6-309 Related Topics.................................................................6-310 SEND_DATA ...................................................................................6-311 Syntax ......................................................................................6-311 Category ..................................................................................6-311 Description ..............................................................................6-311 Examples .................................................................................6-312 Related Topics .........................................................................6-312 SEND_MESSAGE...........................................................................6-313 Syntax ......................................................................................6-313 Category ..................................................................................6-313 Description ..............................................................................6-313 Examples .................................................................................6-314 Related Topics .........................................................................6-314 SEND_TABLE.................................................................................6-316 Syntax ......................................................................................6-316 Category ..................................................................................6-316 Description ..............................................................................6-316 Qualifiers .................................................................................6-317 Examples .................................................................................6-317 Related Topics .........................................................................6-317 SET ACCESS...................................................................................6-319 Syntax ......................................................................................6-319 Category ..................................................................................6-319 Description ..............................................................................6-319 Note: ...............................................................................6-319 Qualifiers .................................................................................6-321 Related Topics.................................................................6-322 SET BROADCAST..........................................................................6-323 Syntax ......................................................................................6-323 Category ..................................................................................6-323

xxxv IAF 8.0 DML

Description .............................................................................. 6-323 SET CAT_FILTER........................................................................... 6-324 Syntax...................................................................................... 6-324 Category .................................................................................. 6-324 Description .............................................................................. 6-324 SET DATABASE............................................................................. 6-325 Syntax...................................................................................... 6-325 Category .................................................................................. 6-325 Description .............................................................................. 6-325 Qualifier .................................................................................. 6-325 Examples ........................................................................ 6-326 Related Topics ................................................................ 6-326 SET DATE_FORMAT..................................................................... 6-327 Syntax...................................................................................... 6-327 Category .................................................................................. 6-327 Description .............................................................................. 6-327 Examples ........................................................................ 6-327 Related Topics ................................................................ 6-327 SET DEFAULT................................................................................ 6-329 Syntax...................................................................................... 6-329 SET ENTRY_MENU ...................................................................... 6-330 Syntax...................................................................................... 6-330 Category .................................................................................. 6-330 Description .............................................................................. 6-330 Examples ........................................................................ 6-331 Related Topics ................................................................ 6-331 SET GLOBAL EXIT FORM........................................................... 6-332 Syntax...................................................................................... 6-332 Category .................................................................................. 6-332 Description .............................................................................. 6-332 Related Topics......................................................................... 6-334 SET GLOBAL EXIT OFF............................................................... 6-335 Syntax...................................................................................... 6-335 Category .................................................................................. 6-335 Description .............................................................................. 6-335 Related Topics......................................................................... 6-335 SET HELP OFF ............................................................................... 6-336 Syntax...................................................................................... 6-336 Category .................................................................................. 6-336 Description .............................................................................. 6-336 Related Topics ................................................................ 6-336 SET HELP ON................................................................................. 6-337 Syntax...................................................................................... 6-337 Category .................................................................................. 6-337

xxxvi IAF 8.0 DML

Description ..............................................................................6-337 Related Topics.................................................................6-337 SET ICON_NAME ..........................................................................6-338 Syntax ......................................................................................6-338 Category ..................................................................................6-338 Description ..............................................................................6-338 Examples.........................................................................6-338 Related Topics.................................................................6-338 SET INPUT BACKGROUND.........................................................6-339 Syntax ......................................................................................6-339 Category ..................................................................................6-339 Description ..............................................................................6-339 Example ..........................................................................6-339 Related Topics.................................................................6-339 SET INPUT FOREGROUND..........................................................6-340 Set Syntax ................................................................................6-340 Category ..................................................................................6-340 Description ..............................................................................6-340 Example ..........................................................................6-340 Related Topics.................................................................6-340 SET INTERRUPT ............................................................................6-341 Syntax ......................................................................................6-341 Category ..................................................................................6-341 Description ..............................................................................6-341 Examples.........................................................................6-341 Related Topics.................................................................6-341 SET KEY..........................................................................................6-343 Set Syntax ................................................................................6-343 Category ..................................................................................6-343 Description ..............................................................................6-343 Qualifiers .................................................................................6-344 Examples.........................................................................6-344 Related Topics.................................................................6-345 SET KEYBOARD............................................................................6-346 Syntax ......................................................................................6-346 Category ..................................................................................6-346 Description ..............................................................................6-346 Example ..........................................................................6-346 Related Topics.................................................................6-346 SET /LOCAL EXIT FORM.............................................................6-347 Syntax ......................................................................................6-347 Category ..................................................................................6-347 Description ..............................................................................6-347 Properties of Local Exit Forms................................................6-349

xxxvii IAF 8.0 DML

Related Topics......................................................................... 6-349 SET LOCAL EXIT OFF.................................................................. 6-350 Syntax...................................................................................... 6-350 Category .................................................................................. 6-350 Description .............................................................................. 6-350 Related Topics......................................................................... 6-350 SET LOCK ...................................................................................... 6-351 Syntax...................................................................................... 6-351 Category .................................................................................. 6-351 Description .............................................................................. 6-351 Option Keywords .................................................................... 6-352 Examples ........................................................................ 6-354 Related Topic.................................................................. 6-354 SET LOCK_TIMEOUT .................................................................. 6-356 Syntax...................................................................................... 6-356 Category .................................................................................. 6-356 Description .............................................................................. 6-356 iBrowser-specific Behavior ............................................ 6-356 Example.......................................................................... 6-357 Related Topics ................................................................ 6-357 SET LOG_FILE............................................................................... 6-358 Syntax...................................................................................... 6-358 Category .................................................................................. 6-358 Description .............................................................................. 6-358 Example 1....................................................................... 6-358 Example 2....................................................................... 6-358 Examples: ....................................................................... 6-358 Related Topics ................................................................ 6-359 SET LOG_LEVEL .......................................................................... 6-360 Syntax...................................................................................... 6-360 Category .................................................................................. 6-360 Description .............................................................................. 6-360 Example 1....................................................................... 6-360 Example 2....................................................................... 6-360 Related Topics ................................................................ 6-360 SET MASK_CURRENCY_SIGN................................................... 6-361 Syntax...................................................................................... 6-361 Category .................................................................................. 6-361 Description .............................................................................. 6-361 Related Topics......................................................................... 6-361 SET MASK_DIGIT_SEPARATOR ................................................ 6-362 Syntax...................................................................................... 6-362 Category .................................................................................. 6-362 Description .............................................................................. 6-362

xxxviii IAF 8.0 DML

Related Topics .........................................................................6-362 SET MASK_RADIX_POINT..........................................................6-363 Syntax ......................................................................................6-363 Category ..................................................................................6-363 Description ..............................................................................6-363 Related Topics .........................................................................6-363 SET NOVERIFY..............................................................................6-364 Syntax ......................................................................................6-364 Category ..................................................................................6-364 Description ..............................................................................6-364 Related Topics .........................................................................6-364 SET OVERFLOW............................................................................6-365 Syntax ......................................................................................6-365 Category..........................................................................6-365 Description......................................................................6-365 Example ..........................................................................6-365 Related Topics.................................................................6-365 SET PERFORM ...............................................................................6-366 Syntax ......................................................................................6-366 Category ..................................................................................6-366 Description ..............................................................................6-366 Option Keywords.....................................................................6-366 Example ..........................................................................6-367 Related Topics.................................................................6-367 SET PRECISION .............................................................................6-368 Syntax ......................................................................................6-368 Category ..................................................................................6-368 Description ..............................................................................6-368 Examples.........................................................................6-369 Related Topics.................................................................6-369 SET PROMPT ..................................................................................6-370 Syntax ......................................................................................6-370 Category ..................................................................................6-370 Description ..............................................................................6-370 Examples.........................................................................6-370 Reference ........................................................................6-370 SET SCREEN ..................................................................................6-371 Syntax ......................................................................................6-371 Category ..................................................................................6-371 Description ..............................................................................6-371 Examples.........................................................................6-372 Related Topics.................................................................6-372 SET SHADOWS ..............................................................................6-373 Syntax ......................................................................................6-373

xxxix IAF 8.0 DML

Category .................................................................................. 6-373 Description .............................................................................. 6-373 Example.......................................................................... 6-373 Related Topics ................................................................ 6-373 SET STATUS_FREQUENCY ......................................................... 6-374 Syntax...................................................................................... 6-374 Category .................................................................................. 6-374 Description .............................................................................. 6-374 Examples................................................................................. 6-374 Related Topics......................................................................... 6-374 SET SYSTEM.................................................................................. 6-375 Syntax...................................................................................... 6-375 Category .................................................................................. 6-375 Description .............................................................................. 6-375 Examples ........................................................................ 6-375 Related Topics ................................................................ 6-375 SET TIMEOUT ............................................................................... 6-376 Syntax...................................................................................... 6-376 Category .................................................................................. 6-376 Description .............................................................................. 6-376 iBrowser-specific Behavior ............................................ 6-376 Examples ........................................................................ 6-377 Related Topics ................................................................ 6-377 SET TITLE_BAR ............................................................................ 6-378 Syntax...................................................................................... 6-378 Category .................................................................................. 6-378 Description .............................................................................. 6-378 Examples ........................................................................ 6-378 Related Topics ................................................................ 6-378 SET TITLE_FORM......................................................................... 6-379 Syntax...................................................................................... 6-379 Category .................................................................................. 6-379 Description .............................................................................. 6-379 Examples ........................................................................ 6-379 Related Topics ................................................................ 6-379 SET VERIFY................................................................................... 6-380 Syntax...................................................................................... 6-380 Category .................................................................................. 6-380 Description .............................................................................. 6-380 Related Topics......................................................................... 6-380 SET WD........................................................................................... 6-381 Syntax...................................................................................... 6-381 Category .................................................................................. 6-381 Description .............................................................................. 6-381

xl IAF 8.0 DML

SHOW CAT_FILTER ......................................................................6-382 Syntax ......................................................................................6-382 Category ..................................................................................6-382 Description ..............................................................................6-382 Related Topics .........................................................................6-382 SHOW DATABASE.........................................................................6-383 Syntax ......................................................................................6-383 Category ..................................................................................6-383 Description ..............................................................................6-383 Related Topics.................................................................6-383 SHOW DATE_FORMAT.................................................................6-384 Syntax ......................................................................................6-384 Category ..................................................................................6-384 Description ..............................................................................6-384 Related Topics.................................................................6-384 SHOW DEFAULT............................................................................6-385 Syntax ......................................................................................6-385 Category ..................................................................................6-385 Description ..............................................................................6-385 SHOW ENTRY_MENU ..................................................................6-386 Syntax ......................................................................................6-386 Category ..................................................................................6-386 Description ..............................................................................6-386 Related Topics.................................................................6-386 SHOW EXIT FORM........................................................................6-387 Syntax ......................................................................................6-387 Category ..................................................................................6-387 Description ..............................................................................6-387 Related Topics .........................................................................6-387 SHOW FIELDS FOR.......................................................................6-388 Syntax ......................................................................................6-388 Category ..................................................................................6-388 Description ..............................................................................6-388 Examples.........................................................................6-388 Related Topics.................................................................6-388 SHOW HELP ...................................................................................6-390 Syntax ......................................................................................6-390 Category ..................................................................................6-390 Description ..............................................................................6-390 Related Topics.................................................................6-390 SHOW HOSTID ..............................................................................6-391 Syntax ......................................................................................6-391 Category ..................................................................................6-391 Description ..............................................................................6-391

xli IAF 8.0 DML

SHOW ICON NAME ...................................................................... 6-392 Syntax...................................................................................... 6-392 Category .................................................................................. 6-392 Description .............................................................................. 6-392 Related Topics......................................................................... 6-392 SHOW INPUT................................................................................. 6-393 Syntax...................................................................................... 6-393 Category .................................................................................. 6-393 Description .............................................................................. 6-393 Related Topics......................................................................... 6-393 SHOW INTERRUPT....................................................................... 6-394 Syntax...................................................................................... 6-394 Category .................................................................................. 6-394 Description .............................................................................. 6-394 Related Topics ................................................................ 6-394 SHOW KEYBOARD ...................................................................... 6-395 Syntax...................................................................................... 6-395 Category .................................................................................. 6-395 Description .............................................................................. 6-395 Related Topics ................................................................ 6-395 SHOW LOCK.................................................................................. 6-396 Syntax...................................................................................... 6-396 Category .................................................................................. 6-396 Description .............................................................................. 6-396 Related Topic.................................................................. 6-396 SHOW LOCK_TIMEOUT.............................................................. 6-397 Syntax...................................................................................... 6-397 Category .................................................................................. 6-397 Description .............................................................................. 6-397 Related Topics......................................................................... 6-397 SHOW LOG .................................................................................... 6-398 Syntax...................................................................................... 6-398 Category .................................................................................. 6-398 Description .............................................................................. 6-398 Example.......................................................................... 6-398 Related Topics......................................................................... 6-398 SHOW MASK_CURRENCY_SIGN .............................................. 6-399 Syntax...................................................................................... 6-399 Category .................................................................................. 6-399 Description .............................................................................. 6-399 Related Topics......................................................................... 6-399 SHOW MASK_DIGIT_SEPARATOR............................................ 6-400 Syntax...................................................................................... 6-400 Category .................................................................................. 6-400

xlii IAF 8.0 DML

Description ..............................................................................6-400 Related Topics .........................................................................6-400 SHOW MASK_RADIX_POINT .....................................................6-401 Syntax ......................................................................................6-401 Category ..................................................................................6-401 Description ..............................................................................6-401 Related Topics .........................................................................6-401 SHOW OVERFLOW.......................................................................6-402 Syntax ......................................................................................6-402 Category ..................................................................................6-402 Description ..............................................................................6-402 Related Topic ..................................................................6-402 SHOW PERFORM ..........................................................................6-403 Syntax ......................................................................................6-403 Category ..................................................................................6-403 Description ..............................................................................6-403 Related Topics.................................................................6-403 SHOW PLATFORM ........................................................................6-404 Syntax ......................................................................................6-404 Category ..................................................................................6-404 Description ..............................................................................6-404 SHOW PRECISION ........................................................................6-405 Syntax ......................................................................................6-405 Category ..................................................................................6-405 Description ..............................................................................6-405 Related Topics.................................................................6-405 SHOW PROMPT .............................................................................6-406 Syntax ......................................................................................6-406 Category ..................................................................................6-406 Description ..............................................................................6-406 Related Topics .........................................................................6-406 SHOW SHADOWS .........................................................................6-407 Syntax ......................................................................................6-407 Category ..................................................................................6-407 Description ..............................................................................6-407 Related Topics.................................................................6-407 SHOW STATUS_FREQUENCY.....................................................6-408 Syntax ......................................................................................6-408 Category ..................................................................................6-408 Description ..............................................................................6-408 Related Topics .........................................................................6-408 SHOW SYSTEM .............................................................................6-409 Syntax ......................................................................................6-409 Category ..................................................................................6-409

xliii IAF 8.0 DML

Description .............................................................................. 6-409 Related Topics......................................................................... 6-409 SHOW TABLES FOR ..................................................................... 6-410 Syntax...................................................................................... 6-410 Category .................................................................................. 6-410 Description .............................................................................. 6-410 Examples ........................................................................ 6-410 Related Topics ................................................................ 6-410 SHOW TARGETID ......................................................................... 6-412 Syntax...................................................................................... 6-412 Category .................................................................................. 6-412 Description .............................................................................. 6-412 SHOW TIMEOUT........................................................................... 6-413 Syntax...................................................................................... 6-413 Category .................................................................................. 6-413 Description .............................................................................. 6-413 Related Topics ................................................................ 6-413 SHOW TITLE_BAR ....................................................................... 6-414 Syntax...................................................................................... 6-414 Category .................................................................................. 6-414 Description .............................................................................. 6-414 Related Topics......................................................................... 6-414 SHOW TITLE_FORM .................................................................... 6-415 Syntax...................................................................................... 6-415 Category .................................................................................. 6-415 Description .............................................................................. 6-415 Related Topics ................................................................ 6-415 SHOW VERIFY .............................................................................. 6-416 Syntax...................................................................................... 6-416 Category .................................................................................. 6-416 Description .............................................................................. 6-416 Related Topics......................................................................... 6-416 SHOW WD ...................................................................................... 6-417 Syntax...................................................................................... 6-417 Category .................................................................................. 6-417 Description .............................................................................. 6-417 SIGNATURE ................................................................................... 6-418 General Purpose ...................................................................... 6-418 Statement Syntax..................................................................... 6-418 Implicit Block Actions ............................................................ 6-419 Special Considerations ............................................................ 6-419 Specific Qualifiers................................................................... 6-419 /AUDIT ................................................................................... 6-419 Syntax............................................................................. 6-419

xliv IAF 8.0 DML

Description......................................................................6-419 Example ..........................................................................6-420 /DATETIME ............................................................................6-420 Syntax .............................................................................6-420 Description......................................................................6-420 Example ..........................................................................6-420 /ERASE ...................................................................................6-420 /FACILITY ..............................................................................6-420 Syntax .............................................................................6-420 Description......................................................................6-420 /FAILURE ...............................................................................6-421 Syntax .............................................................................6-421 Description......................................................................6-421 Example ..........................................................................6-421 /NOAUDIT..............................................................................6-421 Description......................................................................6-421 Example ..........................................................................6-421 /PASSWORD1.........................................................................6-422 Syntax .............................................................................6-422 Description......................................................................6-422 Example ..........................................................................6-422 /PASSWORD2.........................................................................6-422 Syntax .............................................................................6-422 Description......................................................................6-422 Example ..........................................................................6-422 /PURPOSE ..............................................................................6-423 Syntax .............................................................................6-423 Description......................................................................6-423 Example ..........................................................................6-423 /RECALL ................................................................................6-423 /SAVE ......................................................................................6-424 /SUCCESS...............................................................................6-424 Syntax .............................................................................6-424 Example ..........................................................................6-424 /USERNAME1 ........................................................................6-424 Syntax .............................................................................6-424 Description......................................................................6-424 Example ..........................................................................6-425 /USERNAME2 ........................................................................6-425 Syntax .............................................................................6-425 Description......................................................................6-425 Example ..........................................................................6-425 /USER1-5 ................................................................................6-425 Syntax .............................................................................6-425

xlv IAF 8.0 DML

Description ..................................................................... 6-425 Example.......................................................................... 6-425 /VALIDATION_FORM .......................................................... 6-426 Syntax............................................................................. 6-426 Description ..................................................................... 6-426 Example.......................................................................... 6-426 Exit Status ............................................................................... 6-426 SLEEP.............................................................................................. 6-427 Syntax...................................................................................... 6-427 Description .............................................................................. 6-427 START_GTID .................................................................................. 6-428 Syntax...................................................................................... 6-428 Category .................................................................................. 6-428 Description .............................................................................. 6-428 Related Topicsf........................................................................ 6-428 START_STREAM ........................................................................... 6-430 Syntax...................................................................................... 6-430 Category .................................................................................. 6-430 Description .............................................................................. 6-430 Qualifiers................................................................................. 6-431 Examples: ....................................................................... 6-432 Examples: ....................................................................... 6-432 Example:......................................................................... 6-433 Examples: ....................................................................... 6-434 Examples: ....................................................................... 6-435 Example:......................................................................... 6-437 Examples: ....................................................................... 6-438 Example:......................................................................... 6-441 Examples: ....................................................................... 6-442 Examples: ....................................................................... 6-445 Examples ........................................................................ 6-445 Related Topics ................................................................ 6-446 START_TRANSACTION ............................................................... 6-447 Syntax...................................................................................... 6-447 Category .................................................................................. 6-447 Description .............................................................................. 6-447 Example.......................................................................... 6-447 Related Topics ................................................................ 6-448 SWITCH .......................................................................................... 6-449 Syntax...................................................................................... 6-449 Category .................................................................................. 6-449 Description .............................................................................. 6-449 Qualifiers................................................................................. 6-450 Example.......................................................................... 6-450

xlvi IAF 8.0 DML

Related Topics.................................................................6-450 SWITCH_BASE ..............................................................................6-451 Syntax ......................................................................................6-451 Category ..................................................................................6-451 Description ..............................................................................6-451 Example ..........................................................................6-453 Related Topics.................................................................6-454 TABLE_SEARCH............................................................................6-455 Syntax ......................................................................................6-455 Category ..................................................................................6-455 Description ..............................................................................6-455 Qualifiers .................................................................................6-456 Example ..........................................................................6-463 Related Topics.................................................................6-464 TRANSFER .....................................................................................6-465 Syntax ......................................................................................6-465 Category ..................................................................................6-465 Description ..............................................................................6-465 Related Topics.................................................................6-470 TRIGGER.........................................................................................6-471 Syntax ......................................................................................6-471 Category ..................................................................................6-471 Description ..............................................................................6-471 Example ..........................................................................6-471 Related Topics.................................................................6-471 UNLOAD .........................................................................................6-472 Syntax ......................................................................................6-472 Category ..................................................................................6-472 Description ..............................................................................6-472 Examples.........................................................................6-472 Related Topics.................................................................6-472 UTILITIES .......................................................................................6-473 Syntax ......................................................................................6-473 Category ..................................................................................6-473 Description ..............................................................................6-473 Related Topics.................................................................6-473 VERIFY ...........................................................................................6-474 Syntax ......................................................................................6-474 Category ..................................................................................6-474 Description ..............................................................................6-474 Qualifiers .................................................................................6-474 WHILE and END_WHILE ..............................................................6-475 Syntax ......................................................................................6-475 Category ..................................................................................6-475

xlvii IAF 8.0 DML

Description .............................................................................. 6-475 Examples ........................................................................ 6-476 Related Topics ................................................................ 6-476 WRITE............................................................................................. 6-477 Syntax...................................................................................... 6-477 Category .................................................................................. 6-477 Description .............................................................................. 6-477 Example.......................................................................... 6-477 Related Topics ................................................................ 6-477 WRITE_LINE.................................................................................. 6-478 Syntax...................................................................................... 6-478 Category .................................................................................. 6-478 Description .............................................................................. 6-478 Examples ........................................................................ 6-478 Related Topics ................................................................ 6-478 XML_RECEIVE_TABLES............................................................. 6-479 Syntax...................................................................................... 6-479 Category .................................................................................. 6-479 Description .............................................................................. 6-479 Qualifiers................................................................................. 6-479 Examples................................................................................. 6-479 Related Topics......................................................................... 6-480 XML_SEND_TABLE...................................................................... 6-481 Syntax...................................................................................... 6-481 Category .................................................................................. 6-481 Description .............................................................................. 6-481 Qualifiers................................................................................. 6-482 Examples................................................................................. 6-483 DML EXAMPLE #1 ...................................................... 6-483 DML EXAMPLE #2 ...................................................... 6-484 Related Topics......................................................................... 6-484 $ ....................................................................................................... 6-485 Syntax...................................................................................... 6-485 Category .................................................................................. 6-485 Description .............................................................................. 6-485 Related Topics ................................................................ 6-485 Chapter 7 Expressions Data Elements ...................................................................................... 7-2 Literals ........................................................................................ 7-2 Notes About Numeric Literals .................................................... 7-3 Both integer and fraction digits missing: ........................... 7-4 Exponent digits missing: .................................................... 7-4

xlviii IAF 8.0 DML

Table Fields..................................................................................7-5 Examples: ...........................................................................7-5 Computed Fields .................................................................7-6 Variables ......................................................................................7-6 Examples.............................................................................7-6 Special Variables.................................................................7-7 Arrays ..........................................................................................7-7 Examples: ...........................................................................7-7 Operators .....................................................................................7-8 Hierarchy ............................................................................7-8 Arithmetic Operators ..........................................................7-9 Logical Operators .............................................................7-10 Bitwise Operators .............................................................7-10 Relational Operators .........................................................7-11 Internal Datatype Assignments..................................................7-12 Chapter 8 Special Variables and Value Symbols Special Variables ..................................................................................8-2 %ACCOUNT ..............................................................................8-2 %ACTUAL_BREAK ..................................................................8-2 %ADD .........................................................................................8-2 %ADVANCED_USER................................................................8-3 %ARCHIVE ................................................................................8-3 %BITMAP...................................................................................8-3 %BROADCAST..........................................................................8-3 %CAT_FILTER ...........................................................................8-3 %CURRENT_BREAK................................................................8-3 %DATABASE .............................................................................8-4 %DEFAULT_ENGINE ...............................................................8-4 %DELETE...................................................................................8-4 %E ...............................................................................................8-4 %EDIT_MODE ...........................................................................8-5 %ENTRY_MENU .......................................................................8-5 %EXIT_FORM_ACTIVE...........................................................8-5 %EXIT_FORM_ENABLED.......................................................8-5 %EXIT_FORM_FILENAME .....................................................8-5 %EXIT_FORM_FORMNAME ..................................................8-6 %EXIT_FORWARD ...................................................................8-6 %FACILITY................................................................................8-6 %FACILITY_DATABASE .........................................................8-6 %FACILITY_NAME ..................................................................8-7 %FACILITY_SYSTEM ..............................................................8-7 %FIND ........................................................................................8-7

xlix IAF 8.0 DML

%FORM_FILE............................................................................ 8-7 %FORM_NAME ........................................................................ 8-7 %GEM_INIT .............................................................................. 8-7 %GTID ........................................................................................ 8-7 %GTID_LEVEL ......................................................................... 8-8 %HARDWARE........................................................................... 8-8 %HELP_LIBRARY .................................................................... 8-8 %HOSTID................................................................................... 8-8 %INPUT_BACKGROUND ....................................................... 8-8 %INPUT_DATE_FORMAT ....................................................... 8-8 %INPUT_FOREGROUND ........................................................ 8-8 %INPUT_PROMPT.................................................................... 8-9 %INPUT_TIMEOUT.................................................................. 8-9 %INPUT_UPDATE .................................................................... 8-9 %INTERRUPT............................................................................ 8-9 %INTERRUPT_COMMAND .................................................... 8-9 %IS_ADMIN .............................................................................. 8-9 %KEYBOARD_FILE................................................................. 8-9 %LANGUAGE ......................................................................... 8-10 %LOCK_OPTIONS.................................................................. 8-10 %LOG_FILE............................................................................. 8-10 %LOGGING_DEBUG ............................................................. 8-10 %LOGGING_ERROR.............................................................. 8-10 %LOGGING_INFO.................................................................. 8-10 %LOGGING_WARNING ........................................................ 8-10 %MASK_CURRENCY_SIGN................................................. 8-11 %MASK_DIGIT_SEPARATOR .............................................. 8-11 %MASK_RADIX_POINT ....................................................... 8-11 %MODE.................................................................................... 8-11 %MODIFY................................................................................ 8-11 %NODENAME ........................................................................ 8-11 %NOW...................................................................................... 8-11 %OPERATING_SYSTEM ....................................................... 8-11 %PAGE ..................................................................................... 8-12 %PERFORM............................................................................. 8-12 %PI............................................................................................ 8-12 %PID ......................................................................................... 8-12 %PLATFORM .......................................................................... 8-12 %PRECISION........................................................................... 8-13 %PRINT_MODE ...................................................................... 8-13 %QUERY_CUR_REC.............................................................. 8-13 %QUERY_MAX_REC............................................................. 8-13 %QUERY_MODE .................................................................... 8-13 %REPORT_DATE .................................................................... 8-13

l IAF 8.0 DML

%REPORT_FORM_FEEDS .....................................................8-14 %REPORT_PAGE_SIZE ..........................................................8-14 %REPORT_MODE ...................................................................8-14 %REPORT_NAME ...................................................................8-14 %ROW_NUMBER ...................................................................8-14 %SCREEN_MODE...................................................................8-15 %SCREEN_WIDTH .................................................................8-15 %SERVER.................................................................................8-15 %SHADOW_LEVEL................................................................8-15 %SIGNATURE_ID ...................................................................8-15 %STATUS .................................................................................8-15 General..............................................................................8-15 COM Status.......................................................................8-16 Example 1 .........................................................................8-16 %STATUS_FREQUENCY .......................................................8-17 %SYSTEM ................................................................................8-18 %TARGETID ............................................................................8-18 %TEMPORARY_DIRECTORY...............................................8-18 %TERMINAL ...........................................................................8-18 %TEXTFILE_MODE ...............................................................8-18 %THIN_CLIENT ......................................................................8-18 %THIN_CLIENT_CHARSET..................................................8-19 %THIN_CLIENT_HW .............................................................8-19 %THIN_CLIENT_IPCNAME ..................................................8-19 %THIN_CLIENT_MODE ........................................................8-20 %THIN_CLIENT_OS...............................................................8-20 %THIN_CLIENT_REPORT_DIR ............................................8-20 %THIN_CLIENT_TYPE ..........................................................8-20 %THIN_CLIENT_USERNAME ..............................................8-20 %THIN_SERVER .....................................................................8-20 %THIN_SERVER_CHARSET .................................................8-21 %THIN_SERVER_DBCHARSET ...........................................8-21 %THIN_SERVER_HW.............................................................8-21 %THIN_SERVER_IPCNAME .................................................8-21 %THIN_SERVER_MODE .......................................................8-21 %THIN_SERVER_OS ..............................................................8-21 %THIN_SERVER_REPORT_DIR ...........................................8-21 %THIN_SERVER_USERNAME .............................................8-22 %TITLE_FORM .......................................................................8-22 %TODAY ..................................................................................8-22 %TRANS_LEVEL ....................................................................8-22 %UIC.........................................................................................8-22 %UIC_GRP ...............................................................................8-22 %UIC_MEM .............................................................................8-22

li IAF 8.0 DML

%UNIX ..................................................................................... 8-23 %USERNAME ......................................................................... 8-23 %VERSION .............................................................................. 8-23 %WD......................................................................................... 8-23 %XPID ...................................................................................... 8-23 Value Symbols ................................................................................... 8-24 Security Symbols ............................................................................... 8-25 Chapter 9 Built-In Functions String Manipulation Functions ............................................................ 9-3 Numeric Functions............................................................................. 9-11 Date and Time Functions ................................................................... 9-17 Date Arithmetic.................................................................................. 9-19 Data Definition Functions.................................................................. 9-22 Database Functions ................................................................... 9-22 Syntax............................................................................... 9-22 Functions .......................................................................... 9-22 Datatype Functions ................................................................... 9-24 Syntax............................................................................... 9-24 Functions .......................................................................... 9-25 Facility Functions...................................................................... 9-26 Syntax............................................................................... 9-26 Functions .......................................................................... 9-27 Field Functions.......................................................................... 9-28 Syntax............................................................................... 9-28 Functions .......................................................................... 9-29 Index Functions......................................................................... 9-31 Syntax............................................................................... 9-31 Functions .......................................................................... 9-31 Table Functions ......................................................................... 9-33 Syntax............................................................................... 9-33 Functions .......................................................................... 9-33 View Functions ......................................................................... 9-36 Syntax............................................................................... 9-36 Function............................................................................ 9-37 Miscellaneous Metadata Functions........................................... 9-37 File Manipulation Functions.............................................................. 9-42 Miscellaneous Functions.................................................................... 9-45 Multibyte Character Set (MBCS) String Manipulation Features ...... 9-52 Environment Variable Functions ....................................................... 9-58

lii IAF 8.0 DML

Chapter 10 DML Metadata Commands Introduction ........................................................................................10-2 ADD CLASS......................................................................................10-3 Syntax ........................................................................................10-3 Description ................................................................................10-3 Qualifiers ...................................................................................10-3 /DESCRIPTION=string_value .........................................10-3 /REASON=string_expression...........................................10-3 Example ............................................................................10-3 ADD DATABASE..............................................................................10-4 Syntax ........................................................................................10-4 Description ................................................................................10-4 Qualifiers ...................................................................................10-4 /ENGINE=engine_type_keyword.....................................10-4 /SECURITY_TYPE=security_type_keyword ..................10-5 /REASON=string_expression...........................................10-5 Examples...........................................................................10-5 ADD DATATYPE ..............................................................................10-6 Syntax ........................................................................................10-6 Description ................................................................................10-6 Qualifiers ...................................................................................10-6 /CONVERTED_LENGTH=numeric_value......................10-6 /CONVERTED_SCALE=numeric_value.........................10-6 /CONVERTED_TYPE=effective_datatype......................10-6 /IMAGE=string_value ......................................................10-6 /INPUT_MASK=string_value ..........................................10-6 /LENGTH=numeric_value................................................10-7 /NATIVE=native_datatype ...............................................10-7 /OUTPUT_MASK=string_value ......................................10-7 /VALID_VALUES=string_value ......................................10-7 /REASON=string_expression...........................................10-7 /SCALE=numeric_value...................................................10-7 /TO_CONVERTED_ROUTINE=string_value ................10-7 /TO_NATIVE_ROUTINE=string_value ..........................10-7 /USER_ARGUMENT=string_value ................................10-8 Example ............................................................................10-8 ADD DOMAIN..................................................................................10-9 Syntax ........................................................................................10-9 Description ................................................................................10-9 Qualifiers ...................................................................................10-9 /LINK=source_field_name,target_field_name .................10-9 /REASON=string_expression...........................................10-9 /SOURCE_TABLE=table_name ....................................10-10

liii IAF 8.0 DML

/TARGET_TABLE=table_name .................................... 10-10 Example.......................................................................... 10-10 ADD EVENT................................................................................... 10-11 Syntax...................................................................................... 10-11 Description .............................................................................. 10-11 Parameters ............................................................................... 10-11 Qualifiers................................................................................. 10-11 /DESCRIPTION=description ......................................... 10-11 /PROCESS_NAME=process_name............................... 10-11 Example.......................................................................... 10-11 ADD FACILITY.............................................................................. 10-12 Syntax...................................................................................... 10-12 Description .............................................................................. 10-12 Qualifiers................................................................................. 10-12 /CLASS=class_name...................................................... 10-12 /DESCRIPTION=string_value ....................................... 10-12 /DML=(dml_statement) ................................................. 10-12 /HELP=string_value....................................................... 10-12 /MENU_FORM=string_value........................................ 10-12 /MENU_FILE=string_value........................................... 10-12 /REASON=string_expression ........................................ 10-12 /TAG_NAME=string_value ........................................... 10-13 Example.......................................................................... 10-13 ADD_FACILITY_SECURITY ....................................................... 10-14 Syntax...................................................................................... 10-14 Category .................................................................................. 10-14 Description .............................................................................. 10-14 db_handle ....................................................................... 10-14 system_name .................................................................. 10-14 facility_name .................................................................. 10-14 userid .............................................................................. 10-14 accessvalue ..................................................................... 10-15 #variable_name1 ............................................................ 10-15 #variable_name2 ............................................................ 10-15 #variable_name3 ............................................................ 10-15 Example 1....................................................................... 10-15 Example 2....................................................................... 10-16 ADD FIELD .................................................................................... 10-17 Syntax...................................................................................... 10-17 Description .............................................................................. 10-17 Qualifiers................................................................................. 10-17 /DATATYPE=datatype ................................................... 10-17 /DEFAULT=string_value ............................................... 10-17 /DESCRIPTION=string_value ....................................... 10-17

liv IAF 8.0 DML

/DOMAIN=string_value.................................................10-17 /FLAGS=flag_value[,flag_value[,...]] ............................10-17 /HEADING=string_value ...............................................10-18 /HELP=string_value .......................................................10-18 /INITIAL_VALUE=string_expression ...........................10-18 /INPUT_MASK=string_value ........................................10-19 /LENGTH=numeric_value..............................................10-19 /MISSING=string_value.................................................10-19 /OUTPUT_MASK=string_value ....................................10-19 /PROMPT=string_value .................................................10-19 /REASON=string_expression.........................................10-19 /SCALE=numeric_value.................................................10-19 /SHORT_PROMPT=string_value...................................10-19 /USER_ARGUMENT=string_value ..............................10-19 /VALIDATION=dml_string_value .................................10-19 Example ..........................................................................10-19 ADD INDEX....................................................................................10-20 Syntax ......................................................................................10-20 Description ..............................................................................10-20 Qualifiers .................................................................................10-20 /FIELD=field_name........................................................10-20 /FIELD_ASCENDING=field_name...............................10-20 /FIELD_DESCENDING=field_name ............................10-20 /FILL=percentage_fill.....................................................10-21 /FREE=percent_amount .................................................10-21 /GROW=number_bytes ..................................................10-21 /GROWTH=percent_amount..........................................10-21 /MAX_EXTENTS=integer_value ..................................10-21 /MIN_EXTENTS=integer_value....................................10-21 /NODUPLICATES or /DUPLICATES ...........................10-21 /REASON=string_expression.........................................10-21 /SIZE=number_bytes ......................................................10-22 /SIZE=node_size.............................................................10-22 /STORAGE_AREA=storage_area_name.......................10-22 /TABLE=table_name ......................................................10-22 /TYPE=index_type_keyword .........................................10-22 Example: .........................................................................10-22 ORACLE Example: ........................................................10-22 ADD MANAGER_ROLE................................................................10-23 Syntax ......................................................................................10-23 Category ..................................................................................10-23 Description ..............................................................................10-23 Example...................................................................................10-23 ADD MESSAGE..............................................................................10-24

lv IAF 8.0 DML

Syntax...................................................................................... 10-24 Description .............................................................................. 10-24 Qualifiers................................................................................. 10-24 /REASON=string_expression ........................................ 10-24 /SEVERITY=severity_code ........................................... 10-24 /TEXT=string_value....................................................... 10-25 Examples ........................................................................ 10-25 ADD PARAMETER........................................................................ 10-26 Syntax...................................................................................... 10-26 Description .............................................................................. 10-26 Qualifiers................................................................................. 10-26 /ADD_VALUE=start_date,finish_date,string_value...... 10-26 /FLAGS=flag_value[,flag_value[,...]]............................ 10-26 /REASON=string_expression ........................................ 10-26 /VALUE=string_value.................................................... 10-27 Examples ........................................................................ 10-27 ADD PROCEDURE ........................................................................ 10-28 Syntax...................................................................................... 10-28 Description .............................................................................. 10-28 NOTE: ............................................................................ 10-28 Qualifiers................................................................................. 10-28 /DATA_ELEMENT=element_name .................................... [/ data_element_qualifiers]............................................ 10-28 /DESCRIPTION=string_value ....................................... 10-28 /FACILITY=system-name:facility-name ....................... 10-29 /FILE_NAME=string_value........................................... 10-29 /FORM_NAME=string_value........................................ 10-29 /PARAMETER=element_name ............................................... [/parameter_qualifiers]10-29 /REASON=string_expression ........................................ 10-29 Parameter Qualifiers ............................................................... 10-30 /DATATYPE=datatype_name ........................................ 10-30 /LENGTH=numeric_value ............................................. 10-30 /SCALE=numeric_value ................................................ 10-30 /PASS=VALUE|REFERENCE....................................... 10-30 Data Element Qualifiers.......................................................... 10-30 /DATATYPE=datatype_name ........................................ 10-30 /LENGTH=numeric_value ............................................. 10-30 /SCALE=numeric_value ................................................ 10-30 Example.......................................................................... 10-30 ADD ROLE_MANAGER ............................................................... 10-32 Syntax...................................................................................... 10-32 Category .................................................................................. 10-32 Description .............................................................................. 10-32

lvi IAF 8.0 DML

Example...................................................................................10-32 ADD TABLE....................................................................................10-33 Syntax ......................................................................................10-33 Description ..............................................................................10-33 Qualifiers .................................................................................10-33 /ADD_FIELD=global_field_name .................................10-33 /ADD_FIELD=local_field_name BASED_ON global_field_name ............................................ [/field_detail_qualifiers]10-33 /ADD_FIELD=local_field_name COMPUTED_BY (computed_expression) ............................................ [/field_detail_qualifiers]10-33 /ARCHIVE .....................................................................10-34 /CLUSTER .....................................................................10-34 Example Useage: ............................................................10-34 Example: .........................................................................10-34 /CLUSTER=cluster_name ..............................................10-34 /DESCRIPTION=string_value .......................................10-34 /FILL=percent_amount...................................................10-34 /FREE=percent_amount .................................................10-34 GROW=number_of_bytes ..............................................10-35 GROWTH_PCT=percent_amount .................................10-35 /LOCATION=string_value .............................................10-35 /MIN_EXTENTS=integer_value....................................10-35 /MAX_EXTENTS=integer_value ..................................10-35 /NOARCHIVE................................................................10-35 /REASON=string_expression.........................................10-35 /SIZE=number_of_bytes.................................................10-36 /STATIC ..........................................................................10-36 /STOREAGE_AREA=tablespace...................................10-36 /VIRTUAL[=PERSISTENT[,TRANSACTION_CONTROL]] 10-36 Field Detail Qualifiers .............................................................10-36 /DESCRIPTION=string_value .......................................10-37 /HEADING=string_value ...............................................10-37 /HELP=string_value .......................................................10-37 /INPUT_MASK=string_value ........................................10-37 /OUTPUT_MASK=string_value ....................................10-37 /POSITION=numeric_value ...........................................10-37 /PROMPT=string_value .................................................10-37 /SHORT_PROMPT=string_value...................................10-37 Example ..........................................................................10-37 ADD_TABLE_SECURITY .............................................................10-38 Syntax ......................................................................................10-38

lvii IAF 8.0 DML

Category .................................................................................. 10-38 Description .............................................................................. 10-38 database_handle ............................................................. 10-38 table_name ..................................................................... 10-38 userid .............................................................................. 10-38 accessvalue ..................................................................... 10-38 grant_option ................................................................... 10-39 #variable_name1 ............................................................ 10-39 #variable_name2 ............................................................ 10-39 #variable_name3 ............................................................ 10-39 #variable_name4 ............................................................ 10-39 Example 1....................................................................... 10-40 Example 2....................................................................... 10-40 ADD TIME_TRIGGER................................................................... 10-41 Syntax...................................................................................... 10-41 Description .............................................................................. 10-41 Qualifiers................................................................................. 10-41 /DATABASE=string_value ............................................ 10-41 /DESCRIPTION=string_value ....................................... 10-41 /DML=(dml_statement) ................................................. 10-41 /FINISH_DATE=string_value........................................ 10-42 /LOG_FILE=string_value .............................................. 10-42 /QUEUE=string_value ................................................... 10-42 /REASON=string_expression ........................................ 10-42 /RUN_DATES=string_value .......................................... 10-42 /START_DATE=string_value ........................................ 10-42 /USERNAME=username ............................................... 10-42 Example.......................................................................... 10-42 ADD VIEW ..................................................................................... 10-43 Syntax...................................................................................... 10-43 Description .............................................................................. 10-43 Qualifiers................................................................................. 10-43 /ADD_FIELD=local_field_name BASED_ON table_name(field_name) ............................................. [/field_detail_qualifiers]10-43 /ADD_FIELD=local_field_name COMPUTED_BY (computed_expression) ............................................. [/field_detail_qualifiers]10-43 /DESCRIPTION=string_value ....................................... 10-44 /REASON=string_expression ........................................ 10-44 /VIEW_SOURCE=(/view_source_qualifiers) ............... 10-44 Field Detail Qualifiers............................................................. 10-44 /DESCRIPTION=string_value ....................................... 10-44 /HEADING=string_value............................................... 10-44

lviii IAF 8.0 DML

/HELP=string_value .......................................................10-44 /INPUT_MASK=string_value ........................................10-44 /OUTPUT_MASK=string_value ....................................10-45 /PROMPT=string_value .................................................10-45 View Source Qualifiers............................................................10-45 /FIRST=numeric_value ..................................................10-45 /REDUCED_TO=field_name[,field_name[,...]].............10-45 /TABLE=table_name[,table_name[,...]] .........................10-45 /SELECTION=(quoted_selection_expression) ..............10-45 /SORTED_BY=field_name[,field_name[,...]]................10-45 Note: ...............................................................................10-45 /WITH=field_name operator value.................................10-46 /WITH=field_name operator context.field_name ..........10-46 Example ..........................................................................10-46 CONVERT DATABASE..................................................................10-47 Syntax ......................................................................................10-47 Description ..............................................................................10-47 Qualifiers .................................................................................10-47 UNICODE ......................................................................10-47 VARCHAR2 ...................................................................10-49 DELETE CLASS .............................................................................10-51 Syntax ......................................................................................10-51 Description ..............................................................................10-51 Qualifier...................................................................................10-51 Example ..........................................................................10-51 DELETE DATATYPE......................................................................10-52 Syntax ......................................................................................10-52 Description ..............................................................................10-52 Qualifier...................................................................................10-52 /REASON=string_expression.........................................10-52 Example ..........................................................................10-52 DELETE DOMAIN .........................................................................10-53 Syntax ......................................................................................10-53 Description ..............................................................................10-53 NOTE:.............................................................................10-53 Qualifier...................................................................................10-53 /REASON=string_expression.........................................10-53 Example ..........................................................................10-53 DELETE EVENT.............................................................................10-54 Syntax ......................................................................................10-54 Description ..............................................................................10-54 Example ..........................................................................10-54 DELETE FACILITY........................................................................10-55 Syntax ......................................................................................10-55

lix IAF 8.0 DML

Description .............................................................................. 10-55 Qualifier .................................................................................. 10-55 /REASON=string_expression ........................................ 10-55 Example.......................................................................... 10-55 DELETE_FACILITY_SECURITY................................................. 10-56 Syntax...................................................................................... 10-56 Category .................................................................................. 10-56 Description .............................................................................. 10-56 db_handle ....................................................................... 10-56 system_name .................................................................. 10-56 facility_name .................................................................. 10-56 userid .............................................................................. 10-56 #variable_name1 ............................................................ 10-56 #variable_name2 ............................................................ 10-57 Example 1....................................................................... 10-57 Example 2....................................................................... 10-57 DELETE FIELD .............................................................................. 10-58 Syntax...................................................................................... 10-58 Description .............................................................................. 10-58 Qualifier .................................................................................. 10-58 /REASON=string_expression ........................................ 10-58 Example.......................................................................... 10-58 DELETE INDEX............................................................................. 10-59 Syntax...................................................................................... 10-59 Description .............................................................................. 10-59 Qualifier .................................................................................. 10-59 /REASON=string_expression ........................................ 10-59 Example.......................................................................... 10-59 DELETE MANAGER_ROLE......................................................... 10-60 Syntax...................................................................................... 10-60 Category .................................................................................. 10-60 Description .............................................................................. 10-60 Example .................................................................................. 10-60 DELETE MESSAGE....................................................................... 10-61 Syntax...................................................................................... 10-61 Description .............................................................................. 10-61 Qualifier .................................................................................. 10-61 /REASON=string_expression ........................................ 10-61 Example.......................................................................... 10-61 DELETE PARAMETER ................................................................. 10-62 Syntax...................................................................................... 10-62 Description .............................................................................. 10-62 Qualifier .................................................................................. 10-62 /REASON=string_expression ........................................ 10-62

lx IAF 8.0 DML

Example ..........................................................................10-62 DELETE PROCEDURE ..................................................................10-63 Syntax ......................................................................................10-63 Description ..............................................................................10-63 Qualifier...................................................................................10-63 /REASON=string_expression.........................................10-63 Example ..........................................................................10-63 DELETE ROLE_MANAGER .........................................................10-64 Syntax ......................................................................................10-64 Category ..................................................................................10-64 Description ..............................................................................10-64 Example...................................................................................10-64 DELETE TABLE .............................................................................10-65 Syntax ......................................................................................10-65 Description ..............................................................................10-65 Qualifier...................................................................................10-65 /REASON=string_expression.........................................10-65 Example ..........................................................................10-65 DELETE_TABLE_SECURITY.......................................................10-66 Syntax ......................................................................................10-66 Category ..................................................................................10-66 Description ..............................................................................10-66 db_handle........................................................................10-66 table_name ......................................................................10-66 userid...............................................................................10-66 #variable_name1.............................................................10-66 #variable_name2.............................................................10-67 Example 1 .......................................................................10-67 Example 2 .......................................................................10-67 DELETE TIME_TRIGGER.............................................................10-68 Syntax ......................................................................................10-68 Description ..............................................................................10-68 Qualifiers .................................................................................10-68 /REASON=string_expression.........................................10-68 /USERNAME=username................................................10-68 Examples.........................................................................10-68 DELETE VIEW ...............................................................................10-69 Syntax ......................................................................................10-69 Description ..............................................................................10-69 Qualifier...................................................................................10-69 /REASON=string_expression.........................................10-69 Example ..........................................................................10-69 END_METADATA_BATCH ...........................................................10-70 Syntax ......................................................................................10-70

lxi IAF 8.0 DML

Description .............................................................................. 10-70 Qualifiers................................................................................. 10-70 /HANDLE ...................................................................... 10-70 Additional information............................................................ 10-70 GET_FACILITY_SECURITY ........................................................ 10-71 Syntax...................................................................................... 10-71 Category .................................................................................. 10-71 Description .............................................................................. 10-71 db_handle ....................................................................... 10-71 system_name .................................................................. 10-71 facility_name .................................................................. 10-71 userid .............................................................................. 10-72 #variable_name1 ............................................................ 10-72 #variable_name2 ............................................................ 10-72 Example 1....................................................................... 10-72 Example 2....................................................................... 10-73 MODIFY CLASS ............................................................................ 10-74 Syntax...................................................................................... 10-74 Description .............................................................................. 10-74 Qualifiers................................................................................. 10-74 /DESCRIPTION=string_value ....................................... 10-74 /REASON=string_expression ........................................ 10-74 Example.......................................................................... 10-74 MODIFY DATATYPE..................................................................... 10-75 Syntax...................................................................................... 10-75 Description .............................................................................. 10-75 Qualifiers................................................................................. 10-75 /INPUT_MASK=string_value ....................................... 10-75 /LENGTH=numeric_value ............................................. 10-75 /OUTPUT_MASK=string_value ................................... 10-75 /SCALE=numeric_value ................................................ 10-75 /NATIVE=native_datatype............................................. 10-76 /REASON=string_expression ........................................ 10-76 /USER_ARGUMENT=string_value .............................. 10-77 /VALID_VALUES=string_value.................................... 10-77 Example.......................................................................... 10-77 MODIFY FACILITY....................................................................... 10-78 Syntax...................................................................................... 10-78 Description .............................................................................. 10-78 Qualifiers................................................................................. 10-78 /ADD_CHILD=system_name:facility_name................. 10-78 /CLASS=class_name...................................................... 10-78 /DELETE_ALL_LINKS ................................................ 10-78 /DELETE_CHILD=system_name:facility_name .......... 10-78

lxii IAF 8.0 DML

/DESCRIPTION=string_value .......................................10-78 /DML=(dml_statement) ..................................................10-78 /HELP=string_value .......................................................10-78 /MENU_FORM=string_value ........................................10-79 /MENU_FILE=string_value ...........................................10-79 /REASON=string_expression.........................................10-79 /TAG_NAME=string_value............................................10-79 Examples.........................................................................10-79 MODIFY FIELD..............................................................................10-80 Syntax ......................................................................................10-80 Description ..............................................................................10-80 Qualifiers .................................................................................10-80 /DATATYPE=datatype....................................................10-80 /DESCRIPTION=string_value .......................................10-80 /DEFAULT=string_value................................................10-80 /DOMAIN=string_value.................................................10-80 /FLAGS=flag_value[,flag_value[,...]] ............................10-80 /HEADING=string_value ...............................................10-81 /HELP=string_value .......................................................10-81 /INITIAL_VALUE=string_expression ...........................10-81 /INPUT_MASK=string_value ........................................10-82 /LENGTH=numeric_value..............................................10-82 /MISSING=string_value.................................................10-82 /OUTPUT_MASK=string_value ....................................10-82 /PROMPT=string_value .................................................10-82 /REASON=string_expression.........................................10-82 /SCALE=numeric_value.................................................10-82 /SHORT_PROMPT=string_value...................................10-82 /USER_ARGUMENT=string_value ..............................10-82 /VALIDATION=dml_string_value .................................10-82 Example ..........................................................................10-82 MODIFY MESSAGE ......................................................................10-83 Syntax ......................................................................................10-83 Description ..............................................................................10-83 Qualifiers .................................................................................10-83 /REASON=string_expression.........................................10-83 /SEVERITY=severity_code ...........................................10-83 /TEXT=string_value .......................................................10-83 Example ..........................................................................10-84 MODIFY TABLE.............................................................................10-85 Syntax ......................................................................................10-85 Description ..............................................................................10-85 Qualifiers .................................................................................10-85 /ADD_FIELD=global_field_name .................................10-85

lxiii IAF 8.0 DML

/ADD_FIELD=local_field_name BASED_ON global_field_name ............................................. [/field_detail_qualifiers]10-85 /ADD_FIELD=local_field_name COMPUTED_BY (computed_expression) ............................................. [/field_detail_qualifiers]10-85 /ARCHIVE ..................................................................... 10-85 /DELETE_FIELD=field_name ...................................... 10-86 /DESCRIPTION=string_value ....................................... 10-86 /LOCATION=string_value............................................. 10-86 /MODIFY_FIELD=field_name [/field_detail_qualifiers]10-86 /NOARCHIVE ............................................................... 10-86 /REASON=string_expression ........................................ 10-86 /STATIC.......................................................................... 10-87 Field Detail Qualifiers............................................................. 10-87 /DESCRIPTION=string_value ....................................... 10-87 /HEADING=string_value............................................... 10-87 /HELP=string_value....................................................... 10-87 /INPUT_MASK=string_value ....................................... 10-87 /OUTPUT_MASK=string_value ................................... 10-87 /POSITION=numeric_value........................................... 10-87 /PROMPT=string_value ................................................. 10-88 /SHORT_PROMPT=string_value .................................. 10-88 Examples ........................................................................ 10-88 MODIFY TABLE_FIELD............................................................... 10-89 Syntax...................................................................................... 10-89 Description .............................................................................. 10-89 Qualifiers................................................................................. 10-89 /ADD_TRIGGER=(dml_statement) .............................. 10-89 /AUDIT=audit_option[,audit_option[,...]] ..................... 10-89 /DELETE_TRIGGER .................................................... 10-89 /MODIFY_TRIGGER=(dml_statement) ....................... 10-89 /REASON=string_expression ........................................ 10-90 Examples ........................................................................ 10-90 START_METADATA_BATCH....................................................... 10-91 Syntax...................................................................................... 10-91 Description .............................................................................. 10-91 Qualifiers................................................................................. 10-91 /HANDLE ...................................................................... 10-91 /TRANSACTION_AREA.............................................. 10-91 Additional information............................................................ 10-92

lxiv IAF 8.0 DML

Appendix A Input and Output Masks Introduction .........................................................................................A-2 Input Masks .........................................................................................A-3 Example .............................................................................A-3 Output Masks ......................................................................................A-4 Text and Numeric Masking .................................................................A-5 Beginning a Mask.......................................................................A-5 Text Replacement Character.......................................................A-5 Right-Justification Symbol.........................................................A-5 Example .............................................................................A-5 Radix Symbol .............................................................................A-6 Examples............................................................................A-6 Suppression of a Trailing Radix Symbol....................................A-6 Examples............................................................................A-6 Digit Separator Symbol ..............................................................A-7 Examples............................................................................A-7 Protection of Substitute Characters ............................................A-7 Example .............................................................................A-7 Null String Masks.......................................................................A-7 Blank Symbol .............................................................................A-8 Example .............................................................................A-8 Data Larger than Mask ...............................................................A-8 Example .............................................................................A-8 Rounding on Numeric Masks .....................................................A-8 Example .............................................................................A-8 Zero Filling .................................................................................A-8 Examples............................................................................A-8 Zero Suppression ........................................................................A-9 Currency Symbol......................................................................A-10 Example ...........................................................................A-10 Asterisk Filling .........................................................................A-10 Examples..........................................................................A-10 Masking Hierarchy ...................................................................A-11 Examples..........................................................................A-11 Text Substitution Tokens ..........................................................A-12 Examples..........................................................................A-12 Value Tokens.............................................................................A-13 Examples..........................................................................A-14 No Value Token ........................................................................A-14 Example ...........................................................................A-14 Date Masking ....................................................................................A-15 AP .............................................................................................A-15 Examples..........................................................................A-15

lxv IAF 8.0 DML

CC ............................................................................................ A-16 Example........................................................................... A-16 DD............................................................................................ A-16 Examples ......................................................................... A-16 DJ ............................................................................................. A-16 Examples ......................................................................... A-16 DZ ............................................................................................ A-17 Examples ......................................................................... A-17 HH............................................................................................ A-17 Examples ......................................................................... A-17 IT.............................................................................................. A-17 Examples ......................................................................... A-17 LD ............................................................................................ A-18 Examples ......................................................................... A-18 LM............................................................................................ A-18 Examples ......................................................................... A-18 LY............................................................................................. A-19 Example........................................................................... A-19 MI............................................................................................. A-19 Examples ......................................................................... A-19 MM........................................................................................... A-19 Examples ......................................................................... A-19 SD............................................................................................. A-20 Examples ......................................................................... A-20 SH............................................................................................. A-20 Examples ......................................................................... A-20 SM............................................................................................ A-21 Examples ......................................................................... A-21 SS ............................................................................................. A-21 Examples ......................................................................... A-21 YY............................................................................................ A-22 Examples ......................................................................... A-22 Appendix B Executing DML Statements Via Qualifiers Introduction......................................................................................... B-2 Appendix C Predefined Stored Procedures Introduction......................................................................................... C-2 GEM_COMMIT()...................................................................... C-2 GEM_EXECUTE_DML(dml_string)........................................ C-2 GEM_GET_PARAMETER(output_value,parameter_name[,parame ter_date])................................................................................ C-2

lxvi IAF 8.0 DML

GEM_GET_TEXT(output_value,message_name[,argument[,...]])C3 GEM_ROLLBACK() .................................................................C-3 GEM_START_TRANSACTION(type) ..................................... C-3 Examples............................................................................ C-3 Appendix D Interactive Debugger For DML Code Introduction .........................................................................................D-2 Operation.............................................................................................D-2 Invoking the Debugger ...............................................................D-2 SET DEBUG Command.............................................................D-3 Cancel..................................................................................................D-4 Syntax .........................................................................................D-4 Description .................................................................................D-4 Keywords....................................................................................D-4 Examples............................................................................D-5 Deposit ................................................................................................D-6 Syntax .........................................................................................D-6 Description .................................................................................D-6 Examples............................................................................D-6 Examine...............................................................................................D-7 Syntax .........................................................................................D-7 Description .................................................................................D-7 Symbols ......................................................................................D-7 Examples............................................................................D-8 Exit ......................................................................................................D-9 Syntax .........................................................................................D-9 Description .................................................................................D-9 GO .......................................................................................................D-9 Syntax .........................................................................................D-9 Description .................................................................................D-9 Qualifier......................................................................................D-9 /TRACE .............................................................................D-9 HELP.................................................................................................D-10 Syntax .......................................................................................D-10 Description ...............................................................................D-10 Examples..........................................................................D-10 PRINT ...............................................................................................D-10 Syntax .......................................................................................D-10 Description ...............................................................................D-10 QUIT .................................................................................................D-11 Syntax .......................................................................................D-11 Description ...............................................................................D-11

lxvii IAF 8.0 DML

SCROLL ........................................................................................... D-12 Syntax....................................................................................... D-12 Description ............................................................................... D-12 Qualifiers.................................................................................. D-12 /DOWN ........................................................................... D-12 /LEFT .............................................................................. D-12 /RIGHT............................................................................ D-12 /UP................................................................................... D-12 SEARCH........................................................................................... D-13 Syntax....................................................................................... D-13 Description ............................................................................... D-13 Example........................................................................... D-13 SET ................................................................................................... D-14 Syntax....................................................................................... D-14 Description ............................................................................... D-14 Keywords ................................................................................. D-14 Examples ......................................................................... D-18 SHOW............................................................................................... D-19 Syntax....................................................................................... D-19 Description ............................................................................... D-19 Keywords ................................................................................. D-19 STEP ................................................................................................. D-20 Syntax....................................................................................... D-20 Description ............................................................................... D-20 Qualifiers.................................................................................. D-20 /BRANCH ....................................................................... D-20 /CALL ............................................................................. D-20 /INTO .............................................................................. D-21 /OVER ............................................................................. D-21 /RETURN........................................................................ D-21 TYPE ................................................................................................ D-22 Syntax....................................................................................... D-22 Description ............................................................................... D-22 Example........................................................................... D-22 Appendix E DML File Information Introduction..........................................................................................E-2 Limitations ...........................................................................................E-2 DML File Limitations .................................................................E-2 DML Form Limitations .......................................................................E-4 DML Statement Limitations ................................................................E-4 Portable DMC Files .............................................................................E-5

lxviii IAF 8.0 DML

Appendix F Electronic Signature and Audit Record Introduction ......................................................................................... F-2 Electronic Signature Validation Forms ............................................... F-2 GEM_SIGNATURE_AUDIT_MODE System Custimization Variable (SCV) .............................................................................................. F-4 GEM_SIGNATURE_DEFAULT_ USERNAMES SCV ....................................................................... F-4 Electronic Signature Audit Table ........................................................ F-6 Electronic Signature Audit File........................................................... F-8 Signature Identifiers .......................................................................... F-10 Appendix G IAF Transaction Identifiers Introduction .........................................................................................G-2 Transaction Identifiers.........................................................................G-2 Appendix H IAF Transaction Archiving Introduction .........................................................................................H-2 Archiving Phases.................................................................................H-2 Appendix I IAF Character Set Conversion Support Base Character Sets.............................................................................. I-2 Additional Character Sets..................................................................... I-7 Appendix J IAF PDF Reports and PDF File Production Introduction .......................................................................................... J-2 PDF Reports and PDF File Production ................................................ J-3

Appendix K CPANEL DML Statement Introduction .........................................................................................K-2 Example: Perform a DML Command in this Add-in .................K-2 Example: Run a Facility in this Add-in ......................................K-3 Example: Navigate to a URL in this Add-in ..............................K-4 Example: Run a Web Application in this Add-in .......................K-4 Example: Send a Command to a Different Add-in.....................K-4 Replacing TaskPad Items............................................................K-5 Removing TaskPad Items ...........................................................K-6 Automatic Removal of TaskPad Items .......................................K-6

lxix IAF 8.0 DML

Simplified Syntax for DMLDesktop User ................................. K-6 Miscellaneous Usage Notes ....................................................... K-8 Examples............................................................................................. K-9 Example 1 - Add Taskpad item to show web page using the WEB add-in ..................................................................................... K-9 Example 2 - Remove Taskpad item created in Example 1......... K-9 Example 3 - Drillin .................................................................... K-9 Non-Smart Client DMLDesktop Environments ............................... K-10 Appendix L DML Unit Testing DML Unit Testing Introduction..........................................................................................L-2 DML Language Features for Unit Testing ..................................L-2 Unit Tests without RUN_TESTS and ASSERT..........................L-3 Example 1...........................................................................L-3 Example 2...........................................................................L-3 Using RUN_TESTS and ASSERT .............................................L-4 Designing and Developing Unit Tests.........................................L-5 Best Practices ..............................................................................L-5 Console Testing...........................................................................L-5

lxx IAF 8.0 DML

Overview

IAF Data Manipulation Language Manual

Purpose
The IAF Data Manipulation Language Manual is the reference manual for the Data Manipulation Language (DML), which is the fourth generation programming language that IAF provides. This manual describes the language statements, constructs, and built-in functions that comprise the DML, and provides examples of their use. Additionally, this manual provides instructions regarding the use of IAFs interactive DML debugger.

Intended Audience
The IAF Data Manipulation Language Manual is intended primarily for application developers.

Related Documents
Like the IAF Data Manipulation Language Manual, the following documents describe IAF in terms that apply to all operating systems and database engines: IAF Conventions Guide IAF System Reference Manual IAF User Guide For introductory information regarding IAF operation on a particular platform, refer to the IAF tutorial that applies to that platform. For more extensive information regarding IAF operation on a particular operating system or with a particular database engine, refer to the IAF guide that applies to that operating system or database engine. For information on developing DML applications that will be portable from one operating system to another or from one database engine to another, refer to the Guide to Developing Portable IAF DML Applications. For details regarding the documents that comprise the complete IAF documentation set, refer to the IAF Documentation Overview.

-xlii

IAF Data Manipulation Language Manual IAF 8.0 DML

Language Elements
The following table lists and describes the elements that comprise the DML. Language Element Comment Description A comment is descriptive text that begins with an exclamation point (!) and explains the function of a piece of DML code. A form can contain comment lines and DML code. However, a comment must be on a line of its own (i.e. it cannot share a line with DML code). It is not necessary to append a line continuation character (&) to a comment line that continues to one or more subsequent lines. However, an exclamation point must begin the second and subsequent comment lines. Example: PRINT(A= & #A) ! This statement prints the value ! of #A. Form Construct A form construct begins with a form header statement and ends with an END_FORM statement. These statements serve to delimit the DML code that the form contains. Forms are similar to subroutines or modules. Forms produce screen displays or reports, or perform specific processing functions. For details on forms, refer to this manuals Forms And Form Qualifiers chapter. All block constructs except DML blocks consist of a block statement and its qualifiers. A DML block begins with a BEGIN_BLOCK statement and ends with an END_BLOCK statement. Blocks perform individual input, output, and processing functions within a form. For details on blocks, refer to this manuals Blocks And Block Qualifiers chapter.

Block Construct

IAF Data Manipulation Language Manual IAF 8.0 DML

-xliii

Language Element Title Declaration

Description A DML form file can optionally include a title declaration as its first line. A programs title declaration indicates the facility name and text that IAF is to use to construct the programs default screen title. For details on TITLE declarations, refer to this manuals Title Declarations chapter. Example: TITLE SOE, Sales Order Entry

Fixed Display Declaration

Fixed display declarations describe text and/or lines that IAF is to display on screen when initially executing the form that contains the declarations. For details on text and line declarations, refer to this manuals Fixed Display Declarations chapter. Examples: value is TEXT /ROW=4 /COL=10 Total

LINE /ROW=5 /COL=1 /END_COL=78 DML Statement A DML statement is a versatile tool that can include various elements (e.g. qualifiers, keywords, file specifications, database handles, routine names, arguments, expressions, etc.) that IAF accepts as a single complete entity. DML statements enable you to manipulate items such as records and record buffers, screen input and output, and program logic in general. For details on DML statements, refer to this manuals Language Statements chapter.

-xliv

IAF Data Manipulation Language Manual IAF 8.0 DML

Language Element Assignment Statement

Description An assignment statement has the following format: target=source_value and loads the given source value into the given target entity. A target can be a table field, variable, array, or one of the following built-in functions: IS_NULL IS_NULL_ON_STREAM PARAMETER STREAM_DATA TABLE_DATA For details on table fields, variables, and arrays, refer to this manuals EXPRESSIONS chapter. For details on built-in functions, refer to this manuals Built-in Functions chapter.

Expression

An expression is a single data element, or one or more data elements and one or more operators that evaluate to a single value. For details regarding expressions, refer to this manuals EXPRESSIONS chapter.

Language Statements and Constructs

This section presents the Language Statements and Constructs table to enable you to quickly locate DML statements and constructs in this manual. The table lists the statements and constructs alphabetically by name, and includes syntax and one of the following classification codes for each statement and construct: Code BS FS LS Classification Block Statements Form Statements Language Statements

IAF Data Manipulation Language Manual IAF 8.0 DML

-xlv

Code MC

Classification Metadata Commands

Also, for each statement and construct, the table gives the number of the chapter that fully describes the given statement or construct and any applicable qualifiers.

Language Statements and Constructs

Statement or Construct ADD CLASS ADD DATATYPE ADD DOMAIN ADD FACILITY ADD FACILITY SECURITY Syntax ADD CLASS class_name [/qualifiers] ADD DATATYPE datatype_name [/qualifiers] ADD DOMAIN domain_name [/qualifiers] ADD FACILITY system_name:facility_name [/ qualifiers] ADD_FACILITY_SECURITY ([database_handle.]system_name:facility_name, userid, accessvalue) or ADD_FACILITY _SECURITY (#variable_name1, #variable_name2, #variable_name3) ADD FIELD ADD INDEX ADD MESSAGE ADD PARAMETER ADD PROCEDURE ADD TABLE ADD FIELD field_name [/qualifiers] ADD INDEX index_name [/qualifiers] ADD MESSAGE message_name [/qualifiers] ADD PARAMETER parameter_name [/qualifiers] ADD PROCEDURE procedure_name [/qualifiers] ADD TABLE table_name [/qualifiers] M C M C M C M C M C M C 10 10 10 10 10 10 CL M C M C M C M C M C CH# 10 10 10 10 10

-xlvi

IAF Data Manipulation Language Manual IAF 8.0 DML

Language Statements and Constructs

Statement or Construct ADD TABLE SECURITY Syntax ADD_TABLE_SECURITY ([database_handle.]table_name, userid, accessvalue,[grant_option]) or ADD_TABLE_SECURITY (#variable_name1, #variable_name2, #variable_name3, [#variable_name4]) ADD TIME_TRIGGER ADD TO ADD TIME_TRIGGER trigger_name [/qualifiers] ADD TO [database_handle.]table_name [/NOERROR] or ADD TO #variable_name [/NOERROR] ADD VIEW ARCHIVE ADD VIEW view_name [/qualifiers] ARCHIVE [DBMS] [{FROM|SOURCE}] from_database_handle [{TO|TARGET}] to_database_handle& See CASE BEGIN_DISABLE_TRIGGER BEGIN_SIGNAL_TO_STATUS CALL routine_name [(argument1[,argument2[,...]])] M C LS 10 6 M C LS 10 6 CL M C CH# 10

BEGIN_CASE BEGIN_DISABLE _TRIGGER BEGIN_SIGNAL_TO _STATUS CALL

LS LS LS LS

6 6 6 6

IAF Data Manipulation Language Manual IAF 8.0 DML

-xlvii

Language Statements and Constructs

Statement or Construct CALL_WEB_SERVIC E Syntax CALL_WEB_SERVICE & [/ACTION=action] & [/OPERATION=operation] & [/PARAMETER=(NAME=name, TYPE=type, SOURCE=source, TARGET=target)] & [/NAMESPACE=namespace] & [/URL=url] & [/RESPONSE=response] & [/RESULT=(NAME=name, TYPE=type, TARGET=target)] /FAULT_ACTOR /FAULT_CODE /FAULT_STRING CL LS CH# 6

CASE, BEGIN_CASE, CASE ELSE, and END_CASE

BEGIN_CASE (initial_expression) CASE expression[,expression[,...]] or CASE operator expression or CASE expression_a TO expression_b or CASE ELSE END_CASE

LS

CASE ELSE CD CHECK_DOMAIN

See CASE CD directory CHECK_DOMAIN [label_name] & TARGET=table_name(field_name) [/qualifiers] or CHECK_DOMAIN [label_name] & /USING=table_name(field_name) [/qualifiers]

LS LS LS

6 6 6

-xlviii

IAF Data Manipulation Language Manual IAF 8.0 DML

Language Statements and Constructs

Statement or Construct CLEAR ARRAY CLEAR_BUFFER Syntax CLEAR_ARRAY #array () CLEAR_BUFFER [database_handle.]table_name or CLEAR_BUFFER #variable_name CLI CLOSE CLOSE_TABS CLOSE_TEXT COCALL CLI [/qualifiers] command_expression CLOSE datafile_handle CLOSE_TABS [/optional qualifiers] CLOSE_TEXT tag [return_value=] COCALL object_handle.method [(argument1, argument2, )] or [return_value=] COCALL #variable_obj.method [(argument1, argument2, )] or COCALL object_handle.method [(argument1, argument2, )]=assign_expression or COCALL #variable_obj.method [(argument1, argument2, )]=assign_expression COCREATE COCREATE co_name AS object_handle [/ LOCATION=server_location] & [/PREF=server_type1[,server_type2[,server_type3]]] [/ CLIENT] or COCREATE #variable_name AS #variable_obj [/ LOCATION=#variable_loc] & [/PREF=server_type1[,server_type2[,server_type3]]] [/ CLIENT] COMMIT COMPILE COMMIT COMPILE [/qualifiers] input_file_spec [output_file_spec] LS LS 6 6 LS 6 LS LS LS LS LS 6 6 6 6 6 CL LS LS CH# 6 6

IAF Data Manipulation Language Manual IAF 8.0 DML

-xlix

Language Statements and Constructs

Statement or Construct CONNECT CONTINUE CORELEASE CONNECT handle CONTINUE [keyword] CORELEASE obj_handle or CORELEASE #variable_obj CROSS_REFERENCE DCL DELETE CLASS DELETE DATATYPE DELETE DOMAIN DELETE FACILITY DELETE FIELD DELETE FROM CROSS_REFERENCE DCL [/qualifiers] command_expressions DELETE CLASS class_name [/ REASON=string_expression] DELETE DATATYPE datatype_name & [/REASON=string_expression] DELETE DOMAIN domain_name [/ REASON=string_expression] DELETE FACILITY system_name:facility_name & [/REASON=string_expression] DELETE FIELD field_name [/ REASON=string_expression] DELETE [/ARCHIVE] [ALL] FROM [database_handle.]table_name or DELETE [/ARCHIVE] [ALL] FROM #variable_name DELETE INDEX DELETE MESSAGE DELETE PARAMETER DELETE PROCEDURE DELETE INDEX index_name [/ REASON=string_expression] DELETE MESSAGE message_name & [/REASON=string_expression] DELETE PARAMETER parameter_name & [/REASON=string_expression] DELETE PROCEDURE procedure_name & [/REASON=string_expression] M C M C M C M C 10 10 10 10 LS LS M C M C M C M C M C LS 6 6 10 10 10 10 10 6 Syntax CL LS LS LS CH# 6 6 6

-l

IAF Data Manipulation Language Manual IAF 8.0 DML

Language Statements and Constructs

Statement or Construct DELETE TABLE DELETE FACILITY SECURITY Syntax DELETE TABLE table_name [/ REASON=string_expression] DELETE_FACILITY_SECURITY([database_handle. ]system_name:facility_name, userid) or DELETE_FACILITY _SECURITY(#variable_name1, #variable_name2) DELETE TABLE SECURITY DELETE_TABLE_SECURITY ([database_handle.]table_name, userid) or DELETE_TABLE_SECURITY (#variable_name1, #variable_name2) DELETE TIME_TRIGGER DELETE VIEW DIR DISCONNECT DISPLAY DML BLOCK DELETE TIME_TRIGGER trigger_name & [/REASON=string_expression][/ USERNAME=user_name] DELETE VIEW view_name [/ REASON=string_expression] DIR file_specification DISCONNECT handle DISPLAY keyword BEGIN_BLOCK [/DISPLAY_ONLY] block_name dml_code END_BLOCK DOCUMENTATION EDIT EDIT/DICTIONARY EDIT/FORMS EDIT/REPORTS EDIT/SECURITY DOCUMENTATION EDIT filename EDIT/DICTIONARY EDIT/FORMS [file_spec] EDIT/REPORTS [file_spec] EDIT/SECURITY LS LS LS LS LS LS 6 6 6 6 6 6 M C M C LS LS LS BS 10 M C 10 CL M C M C CH# 10 10

10 6 6 6 5

IAF Data Manipulation Language Manual IAF 8.0 DML

-li

Language Statements and Constructs

Statement or Construct EDIT/SYSTEM EDIT/TABLE ELSE ELSE_IF END_CASE END_DISABLE_TRI GGER END_EXECUTE END_IF END_GTID END_SIGNAL_TO_S TATUS END_WHILE ERASE ERROR EDIT/SYSTEM EDIT/TABLE [/FIND] [database_handle.] & [table_name[(field_name1[,field_name2[,...]])]] See IF See IF See CASE END_DISABLE_TRIGGER END_EXECUTE [/HANDLE=connect_handle] & [writeable_data_element[,...]] See IF END_GTID END_SIGNAL_TO_STATUS See WHILE ERASE [/qualifiers] ERROR [/qualifiers] error_text or ERROR EXECUTE EXIT EXECUTE [/HANDLE=connect_handle] [NOWAIT] procedure_name & [(argument1[,argument2[,...]])] EXIT [(exit_status)] LS LS 6 6 Syntax CL LS LS LS LS LS LS LS LS LS LS LS LS LS CH# 6 6 6 6 6 6 6 6 6 6 6 6 6

-lii

IAF Data Manipulation Language Manual IAF 8.0 DML

Language Statements and Constructs

Statement or Construct EXPORT/XML EXPORT/XML & [/FROM=database-tag] & [/FROM=database-tag.table-name] & [/FROM=stream:] & [/FROM=stream:table-name] & [/TABLE=table-name] & /TARGET=target EXTERNAL EXTERNAL file_spec routine_name & [function_return_value] [(argument1[,argument2[,...]])] FETCH stream_name [/qualifiers] FILES [/qualifiers] [file_spec] FIND IN [stream_name:|database_handle.]table_name [/qualifiers] FINISH handle FLOW_BLOCK [block name]/TARGET=data element FLOW_CONNECTOR /required qualifiers[/optional qualifiers] FLOW_NODE/required qualifiers [/optional qualifiers] FORM form_name [(argument1[,argument2[,...]])] & /ROW=numeric_expression & /COL=numeric_expression & /HEIGHT=numeric_expression & /WIDTH=numeric_expression [/qualifiers] GENERATE/FORMS GENERATE/REPORTS LS 6 Syntax CL LS CH# 6

FETCH FILES FIND IN FINISH FLOW_BLOCK FLOW_CONNECTOR FLOW_NODE FORM (NORMAL Form)

LS LS LS LS LS LS LS FS

6 6 6 6 6 6 6 3

GENERATE/FORMS GENERATE/ REPORTS

LS LS

6 6

IAF Data Manipulation Language Manual IAF 8.0 DML

-liii

Language Statements and Constructs

Statement or Construct GET FACILITY SECURITY Syntax GET_FACILITY_SECURITY ([database_handle.]system_name:facility_name, userid) or GET_FACILITY _SECURITY (#variable_name1, #variable_name2) GET TABLE SECURITY GET_TABLE_SECURITY ([database_handle.]table_name, userid) or GET_TABLE_SECURITY (#variable_name1, #variable_name2) GOTO GOTO block_name LS 6 M C 10 CL M C CH# 10

-liv

IAF Data Manipulation Language Manual IAF 8.0 DML

Language Statements and Constructs

Statement or Construct IF, ELSE, ELSE_IF, and END_IF Syntax IF (condition_expression) dml_statement or IF (condition_expression) dml_code ELSE dml_code END_IF or IF (condition_expression) dml_code ELSE_IF (condition_expression) dml_code [ ELSE_IF (condition_expression) dml_code ] END_IF or IF (condition_expression) dml_code ELSE_IF (condition_expression) dml_code [ ELSE_IF (condition_expression) dml_code ] ELSE dml_code END_IF CL LS CH# 6

IAF Data Manipulation Language Manual IAF 8.0 DML

-lv

Language Statements and Constructs

Statement or Construct IMPORT/XML IMPORT/XML & [/CREATE] & [/CREATE_IF] & [/ERROR_TEXT=error-text] & [/REPLACE] & [/RESULTNAME=resultname] & /SOURCE=source & [/TABLE=table-name] & [/TO=database-tag] INPUT_BLOCK INPUT_BLOCK block_name & /ROW=numeric_expression & /COL=numeric_expression & /TARGET=data_element [/qualifiers] INVOKE database_spec AS database_handle [/ qualifiers] ITEM_BLOCK block_name & /ROW=numeric_expression & /COL=numeric_expression & / FACILITY=[database_handle.][system:]facility & [/qualifiers] LICENSE LINE /ROW=numeric_expression & /COL=numeric_expression & / END_ROW=numeric_expression & /END_COL=numeric_expression LOAD file_spec INTO [database_handle.]table_name(field_name) MAIL /TO=to_address [/SUBJECT=subject_text] & /FILE=send_file_spec or MAIL /TO=to_address [/SUBJECT=subject_text] & /TEXT=text_line [/TEXT=text_line[...]] BS 5 Syntax CL LS CH# 6

INVOKE ITEM_BLOCK

LS BS

6 5

LICENSE LINE

LS LS

6 4

LOAD MAIL

LS LS

6 6

-lvi

IAF Data Manipulation Language Manual IAF 8.0 DML

Language Statements and Constructs

Statement or Construct MENU MENU_BLOCK Syntax MENU [database_handle.][system_name:]facility_name MENU_BLOCK block_name / ROW=numeric_expression & /COL=numeric_expression & /item_qualifier[/item_qualifier[...]][/qualifiers] MENU_FORM form_name [(argument1[,argument2[,...]])] & /ROW=numeric_expression & /COL=numeric_expression & /HEIGHT=numeric_expression & /WIDTH=numeric_expression [/qualifiers] MESSAGE [/qualifiers] [database_handle.] & message_name[,argument1[,argument2[,...]]] or MESSAGE MODIFY CLASS MODIFY DATATYPE MODIFY FACILITY MODIFY FIELD MODIFY MESSAGE MODIFY TABLE MODIFY TABLE_FIELD OPEN OPEN_APPLICATIO N MODIFY CLASS class_name [/qualifiers] MODIFY DATATYPE datatype_name [/qualifiers] MODIFY FACILITY system_name:facility_name [/ qualifiers] MODIFY FIELD field_name [/qualifiers] MODIFY MESSAGE message_name [/qualifiers] MODIFY TABLE table_name [/qualifiers] MODIFY TABLE_FIELD table_name(field_name) [/ qualifiers] OPEN unrelated_table_file AS datafile_handle [/ qualifiers] OPEN_APPLICATION application AS handle M C M C M C M C M C M C M C LS LS 10 10 10 10 10 10 10 6 6 CL LS BS CH# 6 5

MENU_FORM

FS

MESSAGE

LS

IAF Data Manipulation Language Manual IAF 8.0 DML

-lvii

Language Statements and Constructs

Statement or Construct OPEN_TEXT Syntax OPEN_TEXT [/APPEND|/CREATE] filename AS tag /PDF=(option=value[, option=value[,...]]) OPEN_URL OUTPUT_BLOCK OPEN_URL /URL=string expression {/DESC=string expression | /NEW WINDOW} OUTPUT_BLOCK block_name & /ROW=numeric_expression & /COL=numeric_expression & /SOURCE=expression [/qualifiers] PAUSE_BLOCK block_name & /ROW=numeric_expression & /COL=numeric_expression [/qualifiers] PERFORM [/NODEADLOCK_EXIT] & form_name [(argument1[,argument2[,...]])] or PERFORM [/BATCH[=PRINT]] & form_file_spec [(argument1[,argument2[,...]]) or PERFORM [/BATCH[=PRINT]][/ NODEADLOCK_EXIT] & form_file_spec form_name [(argument1[,argument2[,...]])] or PERFORM /FACILITY DB.SYS:FAC [(argument1 [,argument2[,...]])] or PERFORM /ARRAY[=count] #array()[form_name] [(argument1[,argument2[,...]])] PRINT PROCEDURE_FORM PRINT [/qualifiers] expression PROCEDURE_FORM form_name [(argument1[,argument2[,...]])] & [/qualifiers] PWD QUERY [/READ_ONLY] [database_handle.] & [table_name[(field_name1[,field_name2[,...]])]] LS FS 6 3 LS BS 6 5 CL LS CH# 6

PAUSE_BLOCK

BS

PERFORM

LS

PWD QUERY

LS LS

6 6

-lviii

IAF Data Manipulation Language Manual IAF 8.0 DML

Language Statements and Constructs

Statement or Construct QUERY_FORM Syntax QUERY_FORM form_name [(argument1[,argument2[,...]])] & /ROW=numeric_expression & /COL=numeric_expression & /HEIGHT=numeric_expression & /WIDTH=numeric_expression & /TABLE=table_name [/qualifiers] RANDOMIZE READ_LINE tag [/TARGET=target_spec] RECEIVE resource_name [/qualifiers] RECEIVE_DATA [/HANDLE=connect_handle] & writeable_data_element[,...] RECEIVE_TABLE [/HANDLE=connect_handle] [REPLACE] target_table_name & [FROM [database_handle.]source_table_name] RELEASE resource_name REPORT REPORT_FORM form_name [(argument1[,argument2[,...]])] & /ROW=numeric_expression & /COL=numeric_expression & /HEIGHT=numeric_expression & /WIDTH=numeric_expression & /TABLE=table_name [/qualifiers] & /PDF=(option=value[, option=value[, ...]] ) REPOSITION BY [-]nnn or REPOSITION TO nnn REWIND_TEXT ROLLBACK SEARCH SEND REWIND_TEXT tag ROLLBACK SEARCH string SEND resource_name [/qualifiers] message_text LS LS LS LS 6 6 6 6 CL FS CH# 3

RANDOMIZE READ_LINE RECEIVE RECEIVE_DATA RECEIVE_TABLE

LS LS LS LS LS

6 6 6 6 6

RELEASE REPORT REPORT_FORM

LS LS FS

6 6 3

REPOSITION

LS

IAF Data Manipulation Language Manual IAF 8.0 DML

-lix

Language Statements and Constructs

Statement or Construct SEND_DATA SEND_MESSAGE SEND_TABLE Syntax SEND_DATA data_element[,data_element[,...]] SEND_MESSAGE numeric_expression, text_expression SEND_TABLE [/HANDLE=connect_handle] [REPLACE] source_table_name & [TO [database_handle.]target_table_name] SET ACCESS table_name [access_mode] & [/SHARE=share_mode] or SET ACCESS table_name & /RMS_OPTIONS=rms_option[,rms_option[,...]] SET BROADCAST SET DATABASE SET DATE_FORMAT SET DEFAULT SET ENTRY_MENU SET BROADCAST broadcast_categories SET [/LOCAL] DATABASE database_handle SET DATE_FORMAT format_name SET DEFAULT directory SET ENTRY_MENU & [database_handle.][system_name:]facility_name or SET ENTRY_MENU SET GLOBAL EXIT FORM SET GLOBAL EXIT FORM SET HELP ON and SET HELP OFF SET ICON_NAME SET INPUT BACKGROUND SET INPUT FOREGROUND SET /GLOBAL EXIT FORM FILENAME FORMNAME(P1, ... Pn) SET /GLOBAL EXIT FORM /FACILITY DB:SYS:FAC(P1, ... Pn) SET HELP ON and SET HELP OFF SET ICON_NAME string_expression SET INPUT BACKGROUND attribute[,attribute[,...]] SET INPUT FOREGROUND attribute[,attribute[,...]] LS LS LS 6 6 6 LS LS LS 6 6 6 LS LS LS LS LS 6 6 6 6 6 CL LS LS LS CH# 6 6 6

SET ACCESS

LS

-lx

IAF Data Manipulation Language Manual IAF 8.0 DML

Language Statements and Constructs

Statement or Construct SET INTERRUPT SET KEY SET KEYBOARD SET LOCAL EXIT FORM Syntax SET INTERRUPT dml_statement_expression SET KEY physical_key_name [/qualifiers] logical_key_name SET KEYBOARD filename SET [/LOCAL] EXIT FORM FILENAME FORMNAME (P1, ... Pn) SET [/LOCAL] EXIT FORM FORMNAME (P1, ... Pn) SET [/LOCAL] EXIT FORM /FACILITY DB:SYS:FAC (P1, ... Pn) SET LOCAL EXIT OFF SET LOCK SET LOCK_TIMEOUT SET MASK_CURRENCY_ SIGN SET MASK_DIGIT_SEPA RATOR SET MASK_RADIX_POIN T SET PERFORM SET PRECISION SET PROMPT SET SCREEN SET SHADOWS SET STATUS_FREQUENC Y SET /LOCAL EXIT OFF SET LOCK option_keyword[,option_keyword[,...]] SET LOCK_TIMEOUT seconds SET MAK_CURRENCY_SIGN currency-sign-character SET MASK_DIGIT_SEPARATOR digit-separator SET MASK_RADIX_POINT radix-point-character LS 6 LS 6 LS LS LS LS 6 6 6 6 CL LS LS LS LS CH# 6 6 6 6

SET PERFORM option_keyword SET PRECISION floating_point_number SET PROMPT expression SET SCREEN option_keyword[,option_keyword] SET SHADOWS number SET STATUS_FREQUENCY seconds

LS LS LS LS LS LS

6 6 6 6 6 6

IAF Data Manipulation Language Manual IAF 8.0 DML

-lxi

Language Statements and Constructs

Statement or Construct SET SYSTEM SET TIMEOUT SET TITLE_BAR SET TITLE_FORM SET VERIFY and SET NOVERIFY SET WD SHOW CAT_FILTER SHOW DATABASE SHOW DATE_FORMAT SHOW DEFAULT SHOW ENTRY_MENU SHOW EXIT FORM SHOW FIELDS FOR SHOW HELP SHOW HOSTID SHOW ICON_NAME SHOW INPUT SHOW INTERRUPT SHOW KEYBOARD SHOW LOCK SHOW MASK_CURRENCY_ SIGN Syntax SET SYSTEM [database_handle.]system_name SET TIMEOUT seconds SET TITLE_BAR string_expression SET TITLE_FORM filename SET VERIFY and SET NOVERIFY SET WD directory SHOW CAT_FILTER SHOW DATABASE SHOW DATE_FORMAT SHOW DEFAULT SHOW ENTRY_MENU SHOW EXIT FORM SHOW FIELDS FOR table_name SHOW HELP SHOW HOSTID SHOW ICON_NAME SHOW INPUT SHOW INTERRUPT SHOW KEYBOARD SHOW LOCK SHOW MASK_CURRENCY_SIGN LS LS LS LS LS LS LS LS LS LS LS LS LS LS LS LS 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 CL LS LS LS LS LS CH# 6 6 6 6 6

-lxii

IAF Data Manipulation Language Manual IAF 8.0 DML

Language Statements and Constructs

Statement or Construct SHOW MASK_DIGIT_SEPA RATOR SHOW MASK_RADIX_POIN T SHOW LOCK_TIMEOUT SHOW PERFORM SHOW PLATFORM SHOW PRECISION SHOW PROMPT SHOW SHADOWS SHOW STATUS_FREQUENC Y SHOW SYSTEM SHOW TABLES FOR SHOW TARGETID SHOW TIMEOUT SHOW TITLE_BAR SHOW TITLE_FORM SHOW VERIFY SHOW WD SIGNATURE START_GTID Syntax SHOW MASK_DIGIT_SEPARATOR CL LS CH# 6

SHOW MASK_RADIX_POINT

LS

SHOW LOCK_TIMEOUT SHOW PERFORM SHOW PLATFORM SHOW PRECISION SHOW PROMPT SHOW SHADOWS SHOW STATUS_FREQUENCY

LS LS LS LS LS LS LS

6 6 6 6 6 6 6

SHOW SYSTEM SHOW TABLES FOR field_name SHOW TARGETID SHOW TIMEOUT SHOW TITLE_BAR SHOW TITLE_FORM SHOW VERIFY SHOW WD SIGNATURE START_GTID

LS LS LS LS LS LS LS LS LS LS

6 6 6 6 6 6 6 6 6 6

IAF Data Manipulation Language Manual IAF 8.0 DML

-lxiii

Language Statements and Constructs

Statement or Construct START_STREAM Syntax START_STREAM stream_name & /TABLE=[database_handle.]table_name[,table_name [,...]] & [/qualifiers] or START_STREAM stream_name & /TABLE=#variable_name[,#variable_name[,...]] [/qualifiers] START_TRANSACTION SWITCH START_TRANSACTION [READ_ONLY] SWITCH form_name [(argument1[,argument2[,...]])] or SWITCH form_file_spec & [form_name] [(argument1[,argument2[,...]])] SWITCH_BASE SWITCH_BASE [%EXIT] or SWITCH_BASE form_name [(argument1[,argument2[,...]])] or SWITCH_BASE form_file_spec & [form_name][(argument1[,argument2[,...]])] TABLE_FORM (TABLE_EDIT Form) TABLE_FORM form_name [(argument1[,argument2[,...]])] & /ROW=numeric_expression & /COL=numeric_expression & /HEIGHT=numeric_expression & /WIDTH=numeric_expression & /TABLE=table_name [/qualifiers] TABLE_SEARCH [database_handle.] & table_name(field_name1[,field_name2[,...]]) [/ qualifiers] TEXT /ROW=numeric_expression / COL=numeric_expression & [{token}]text TRANSFER command_filename FS 3 LS 6 LS LS 6 6 CL LS CH# 6

TABLE_SEARCH

LS

TEXT TRANSFER

LS LS

4 6

-lxiv

IAF Data Manipulation Language Manual IAF 8.0 DML

Language Statements and Constructs

Statement or Construct TRIGGER UNLOAD UTILITIES Syntax TRIGGER trigger_name UNLOAD file_spec FROM & [database_handle.]table_name(field_name) UTILITIES or UTILITY WHILE and END_WHILE WHILE (condition_expression) dml_statement or WHILE (condition_expression) dml_code END_WHILE WRITE WRITE_LINE XML_RECEIVE_TAB LES XML_SEND_TABLE WRITE tag data WRITE_LINE tag [data] XML_RECEIVE_TABLES XML_SEND_TABLE table-name & [/TABLE_OPTIONS=table-options] & [/FIELD_OPTIONS=field-options] YESNO_BLOCK YESNO_BLOCK block_name / ROW=numeric_expression & /COL=numeric_expression [/qualifiers] $ operating_system_command BS 5 LS LS LS 6 6 6 LS 6 CL LS LS LS CH# 6 6 6

LS

IAF Data Manipulation Language Manual IAF 8.0 DML

-lxv

Chapter 1

Program-Data Independence

Program-data independence is the measure of independence that exists between programs and data definitions. The greater the effect that data definition changes have on the programs that use that data, the less program-data independence there is. The ideal situation is one in which there is complete program- data independence. When there is complete program-data independence, data definition changes are immediately evident to the programs that use that data, and the changes do not require programmer intervention or program recompilation.

1-2

Program-Data Independence IAF 8.0 DML

Achieving ProgramData Independence

Achieving ProgramData Independence

The DML includes facilities to enable you to maximize program-data independence. However, you must follow a basic guideline when programming in the DML in order to fully use these facilities. This guideline is as follows:
Do not hard-code data definition details into DML programs.

Instead of hard-coding data definitions, allow IAF to obtain data definition details from the data dictionary at run-time. For details regarding the data dictionary and the Data Definition Editor which provides access to it, refer to the IAF System Reference Manual. The following table uses some data definition detail examples to illustrate program-data independence maximization methods. Definition Detail field length input mask output mask validation prompt Avoiding Use /LENGTH /INPUT_MASK /OUTPUT_MASK /USING /PROMPT=prompt Use length from definition in data dictionary input mask from definition in data dictionary output mask from definition in data dictionary validation from definition in data dictionary /PROMPT=FIELD_PROMPT (field_name) or prompt from definition in data dictionary

When input data is destined for a table field (due to a /TARGET=table_field or /USING=table_field qualifier) or output data is to come from a table field (due to a /SOURCE=table_field or /USING=table_field qualifier), IAF uses data definition details from the data dictionary at run-time to accomplish the operation. Note that there are input and output block qualifiers that you can use to override specific data dictionary definition details. For details regarding input and output blocks and their qualifiers, refer to this manuals Blocks And Block Qualifiers chapter.

Program-Data Independence IAF 8.0 DML

1-3

Advantages of ProgramData Independence

Advantages of ProgramData Independence

By adhering to the basic guideline in the preceding section and thereby maximizing program-data independence, you stand to gain the following advantages: A reduction in the amount of program code is likely. The data definitions in the data dictionary embody a large amount of implicit code that would otherwise be explicit code in your program. Reducing the amount of code in your program reduces the possibility of program errors occurring, enhances program readability, and makes it easier to perform program modifications. Data definition changes are immediately evident to programs that use that data. When there is complete program-data independence, data definition changes are immediately evident to the programs that use that data, and the changes do not require programmer intervention or program recompilation. This speeds up the system development process and makes prototyping a more viable option. System changes can take place via the data dictionary. System-wide modifications can take place via the data dictionary. The data dictionary then becomes the central point of control for the administration of the database and system.

1-4

Program-Data Independence IAF 8.0 DML

ProgramData Independence Illustration

ProgramData Independence Illustration

The following example illustrates the concept of program-data independence: Suppose you want to change all monetary values in your system so that they have three decimal places instead of two. If all the monetary fields in the system use the user-defined MONEY datatype, and the programs that input and output these fields do not use hard-coded lengths, input masks, or output masks, you can modify the MONEY datatypes scale, input mask, and output mask to accomplish the change system-wide. Changing the definition of the user-defined datatype changes the programs behavior as well as the data, but some elements, such as those that are dynamically positioned still may require some program modifications or re-compilation. For example, when you invoke dynamic calculation possibly in the case of reports, or positioning issues the form may need to be recompiled.

Program-Data Independence IAF 8.0 DML

1-5

Chapter 2

Title Declarations

You can optionally include a TITLE declaration as the first line of any DML form file (program). A programs TITLE declaration indicates the facility name and text that IAF is to use to construct the programs default screen title. If you have defined a title form via the SET TITLE_FORM statement, IAF passes the facility name and title in the TITLE declaration as arguments to the defined title form, which can then use the arguments as desired. If you have not defined a title form via the SET TITLE_FORM statement, IAF uses the title declarations facility name and title text to construct a screen title each time it executes the DML program. For details regarding the definition of title forms, refer to the IAF System Reference Manual. For details regarding the SET TITLE_FORM statement, refer to its description in this manuals LANGUAGE STATEMENTS chapter. For details regarding forms in general, refer to this manuals Forms And Form Qualifiers chapter.

2-2

Title Declarations IAF 8.0 DML

TITLE Declaration Syntax

TITLE Declaration Syntax

TITLE declarations must conform to the following syntax:
TITLE facility_name, title_text

The components of this syntax are as follows: Component facility_name Syntax IAF uses the facility name as part of the default screen title, and to determine the storage area to use for any help text that applies to the given DML program. IAF uses the title text as part of the default screen title. The title text component must be either a quoted literal or the keyword NONE. The keyword NONE indicates that IAF is not to change the current screen titles when executing the given DML program, and the given facility name is to serve only as an indicator of the storage area for any help text that applies to the program.

title_text

Examples:
TITLE SOE, Sales Order Entry TITLE MAINT, CUSTOMER MAINTENANCE TITLE GET_PARTS_SUBR, NONE

Title Declarations IAF 8.0 DML

2-3

Chapter 3

Forms and Form Qualifiers

Forms are similar to subroutines or modules. They produce screen displays or reports, or perform specific processing functions. A form begins with a form header statement and ends with an END_FORM statement. You can create forms via the Forms Generator or a text editor. Forms must conform to the following rules: Each form must have a name that is unique within the file in which it resides. Each form must be one of six available form types. The following table lists these form types and the form header statements that define them, and indicates the purpose of each form type. Form Type NORMAL Form Header Statement FORM Purpose Facilitates general fixedformat screen input and output. Facilitates displaying scrolling windows of selected record sets from one or more tables for inspection and/or editing. Facilitates record queries and maintenance. Facilitates outputting selected record data to disk files. Facilitates processing table information with little or no screen interaction. Facilitates displaying lists of options that end users can select to perform particular functions.

TABLE_EDIT

TABLE_FORM

QUERY REPORT PROCEDURE

QUERY_FORM REPORT_FORM PROCEDURE_FO RM MENU_FORM

MENU

The remainder of this chapter has the following organization: The Introduction section contains information regarding the specification of form header statements and form arguments. It also discusses the statements that perform forms, and the various statuses that forms can return.

3-2

Forms and Form Qualifiers IAF 8.0 DML

A section for each form type (in alphabetical order by form type) describes the given form types typical use, and the form header statement syntax and form qualifiers (options) that are applicable to that form type. The Form Qualifiers section presents full descriptions of all form qualifiers available in the IAF DML. The section consists of a reference table that categorizes the form qualifiers by function and form type, and an alphabetized presentation of form qualifiers, including syntax, descriptions, and examples. For a topical discussion of forms, refer to the IAF Users Guide.

Forms and Form Qualifiers IAF 8.0 DML

3-3

Introduction

Introduction
This section contains information regarding the specification of form header statements and form arguments. This section also details the statements that perform forms, and the various statuses that forms can return.

Form Header Statement Syntax

The syntax for form header statements is as follows:
form_header_statement form_name [(argument1[,argument2[,...]])] [/qualifiers]

Syntax form_header_statement form_name

Form Header The DML statement associated with the type of form you are defining. The name of the form you are defining. A form name must consist only of letters, numbers, and underscores, and must be no longer than 31 characters. IAF uses the form name to identify the help path to use when extracting help information for an input block in the form. Indicates the argument(s) that the form is to accept. Arguments must be valid DML expressions separated by commas and enclosed in parentheses. An expression is a language construct that evaluates to a single value. For details regarding the specification of form arguments, refer to this sections Form Arguments heading. For details regarding expressions, refer to this manuals Expressions chapter. Indicate the options to activate for the given form. For information regarding the qualifiers that apply to a given form header statement, refer to this chapters section that pertains to that form type. For descriptions of all form qualifiers, refer to this chapters Form Qualifiers section.

(argument1[,argument2[,...]])

/qualifiers

3-4

Forms and Form Qualifiers IAF 8.0 DML

Introduction

Form Arguments
IAF allows you to specify an argument list with a form header statement to indicate the arguments that the form is to receive. The argument list must consist of valid DML expressions separated by commas and enclosed in parenthesis. Form argument expressions are local to the form that declares them. Therefore, references to a given form argument can take place only within the form that declares them. The syntax for declaring form arguments is as follows:
(#argument1[,#argument2[,...]])

Example:
PROCEDURE_FORM SET_FLAGS (#CUSTOMER_ID,#FLAGS)

Passing Arguments
The DML PERFORM statement facilitates passing external data as arguments to forms via the following syntax:
PERFORM [filename] form_name[(#argument1[,#argument2[,...]])]

IAF considers simple variables (excluding array elements), simple table fields, and form arguments to be read/write entities, and complex expressions or literals to be read only entities. Therefore, an argument that references a table field passes its contents to the form as a read/write entity, and the called form can modify the contents of the table field. However, it is possible to override this behavior by enclosing the table field argument in parentheses. This causes IAF to pass the table fields contents as a read only entity. Regardless, of whether the calling form passes a given argument as a read/write or read only entity, the called form can write to the argument. However, if the calling form passes the argument as a read only argument, the calling form will not see a change in the arguments value as a result of the called form writing to the argument. The calling form will still see the arguments original value.

Examples:
PERFORM SET_FLAGS (102002,D)

This example performs the SET_FLAGS form, which resides in the current set of forms, and passes it two arguments, which are both literals.
PERFORM CALC_LIBRARY CALC_DISCOUNT(#DISC,#CUST_ID)

This example performs the CALC_DISCOUNT form, which exists in the CALC_LIBRARY file, and passes it two variables as arguments.

Forms and Form Qualifiers IAF 8.0 DML

3-5

Introduction

PERFORM DISPLAY_DETAILS(CUSTOMERS(CUSTOMER_ID))

This example performs the DISPLAY_DETAILS form and passes it the contents of the CUSTOMERS(CUSTOMER_ID) table field. This example allows the DISPLAY_DETAILS form to modify the contents of the CUSTOMERS(CUSTOMER_ID) table field.
PERFORM DISPLAY_DETAILS((CUSTOMERS(CUSTOMER_ID)))

This example performs the DISPLAY_DETAILS form and passes it the contents of the CUSTOMERS(CUSTOMER_ID) table field. Enclosing the CUSTOMERS(CUSTOMER_ID) table field in parentheses prevents the DISPLAY_DETAILS form from modifying the contents of the field.

Argument Scope
Arguments are local to the form that declares them and are not global to the compilation unit (file). Therefore, references to arguments can take place only within the form that declares them. In contrast, normal variables are global to the compilation unit in which they occur. However, a variable can be made local to a given form by passing it as an argument to the form. For example, when IAF performs a form recursively, any argument that the form header statement specifies remains local to the specific form. The following example illustrates the use of form arguments.

3-6

Forms and Form Qualifiers IAF 8.0 DML

Introduction

Example:
PROCEDURE_FORM MAIN (#ACT_DISC) ! Using a discount matrix based on customer group and product ! group, this form determines the largest discount a given ! customer can receive. Each customer has two discount groups. ! This form also ensures that the correct customer and ! parts records are available. PERFORM CALC_DISC (#DISC1, CUSTOMERS(DISC_GRP_1)) PERFORM CALC_DISC (#DISC2, CUSTOMERS(DISC_GRP_2)) IF (#DISC1 > #DISC2) # #ACT_DISC=#DISC1 ELSE #ACT_DISC=#DISC2 END_IF END_FORM

PROCEDURE_FORM CALC_DISC (#DISCOUNT,#DISC_GRP) FIND IN DISCOUNT_MATRIX & /WITH=PART_GRP=PARTS(GROUP) & /WITH=CUST_GRP=#DISC_GRP IF(%STATUS=%NORMAL) #DISCOUNT=DISCOUNT_MATRIX(DISCOUNT) ELSE #DISCOUNT=0 END_IF END_FORM

Forms and Form Qualifiers IAF 8.0 DML

3-7

Introduction

Performing Forms
The DML PERFORM, SWITCH, and SWITCH_BASE statements facilitate directly performing (executing a form). IAF also provides form header statement qualifiers such as /BREAK, /HEADING_FORM, and /DELETE_FORM to facilitate indirectly executing a form. The PERFORM statement has a variety of syntax formats. The following table lists and describes these syntax formats. Syntax PERFORM [/NODEADLOCK_EXIT] & form_name [(argument1[,argument2[,...]])] Effect IAF executes the specified form in the current DML file. IAF executes the first form in the specified DML file. IAF executes the specified form in the specified DML file.

PERFORM [/BATCH[=PRINT]] & file_spec [(argument1[,argument2[,...]])]

PERFORM [/BATCH[=PRINT]] [/NODEADLOCK_EXIT] & file_spec form_name [(argument1[,argument2[,...]])]

The SWITCH and SWITCH_BASE statements are functionally and syntactically similar to the PERFORM statement. However, when executing a form via the SWITCH or SWITCH_BASE statement, the form does not execute within the context of the current form as it does when executed via the PERFORM statement. Instead, the current form exits. Also, the /BATCH qualifier is not applicable to SWITCH and SWITCH_BASE. For more information regarding the SWITCH, SWITCH_BASE, and PERFORM statements, refer to this manuals Language Statements chapter.

Return Status
Immediately after a form executes, its return status is available in the %STATUS special variable. The calling form can examine %STATUS to determine the called forms return status after the called form executes.

3-8

Forms and Form Qualifiers IAF 8.0 DML

Introduction

A form can explicitly specify a return status value via the DML EXIT statement. IAF places the specified status value in the %STATUS variable when control returns to the calling form. If a form exits without executing an EXIT statement with an explicit return status, IAF places a status in the %STATUS variable to indicate the type of exit that took place. For example, if a form exits as a result of an end user pressing the GM_BACK key in response to the forms first input, IAF places the %BACK value symbol in the %STATUS variable. For details regarding %STATUS, %BACK, and other system variables and value symbols, refer to this manuals Special Variables And Value Symbols chapter.

Example:
PROCEDURE_FORM A . . PERFORM B IF(%STATUS=%BACK) GOTO START END_IF END_FORM

PROCEDURE_FORM B INPUT_BLOCK A /ROW=1 /COL=1 /LEN=1 /TARGET=#A IF(#A=B) EXIT(%BACK) END_IF . . . END_FORM

Forms and Form Qualifiers IAF 8.0 DML

3-9

MENU Forms

MENU Forms
MENU forms facilitate linking different forms together to assemble a complete system. A system is a functional hierarchy of facilities and subfacilities. Each MENU form displays a list of options that end users can select to perform particular functions. For example, an order entry system might use a MENU form containing options allowing end users to enter orders, ship goods, maintain inventory records, and perform other related functions. MENU forms can call other MENU forms. The options on a called MENU form represent the sub-facilities of the calling MENU form. For details regarding systems, facilities, and sub-facilities, refer to the IAF System Reference Manual.

Form Header Statement Syntax

Following is the syntax for the MENU_FORM statement, which is the form header statement to use for MENU forms:
MENU_FORM form_name [(argument1[,argument2[,...]])] & /ROW=numeric_expression & /COL=numeric_expression & /HEIGHT=numeric_expression & /WIDTH=numeric_expression [/qualifiers]

Implicit Form Actions

When executing a MENU form, IAF pastes the forms window on the screen, displays in it any specified TEXT output blocks and the specified ITEM block(s) and prompts the end user to select an option (item). The MENU_FORM statements mandatory /HEIGHT and /WIDTH qualifiers govern the size of the form window, and the MENU_FORM statements mandatory /ROW and /COL qualifiers govern the placement of the window on the screen. If no /SORTED_BY qualifier is specified, the set of records will be sorted in Primary ID (PID) sequence. There must be at least one ITEM block in the body of a MENU form. After the end user selects an option, IAF executes the DML code associated with the facility that the given ITEM blocks /FACILITY qualifier specifies. After executing the DML code, IAF unpastes the form window from the screen as the MENU form exits. For details regarding TEXT and ITEM blocks, refer to this manuals Blocks And Block Qualifiers chapter.

3-10

Forms and Form Qualifiers IAF 8.0 DML

MENU Forms

Applicable Qualifiers
The following qualifiers are applicable to the MENU_FORM statement. For details regarding these qualifiers, refer to this chapters Form Qualifiers section.
/ATTRIBUTES/READ_ONLY/TITLE /COL/ROW/WIDTH /DEFAULT_TAG/SYSTEM /HEIGHT/TAG_LENGTH

Example
MENU_FORM /ROW=3 /COL=2 /HEIGHT=20 /WIDTH=78 & /SYSTEM=SALES_ORDERS ! Define the size of the menu, and specify SALES_ORDERS ! as the default system. TEXT /ROW=2 /COL=4 Entry Procedures TEXT /ROW=10 /COL=4 Exit Procedures ITEM_BLOCK ORDER_ENTRY /ROW=3 /COL=6 & /FACILITY=ORDER_ENTRY ITEM_BLOCK ORDER_PRINT /ROW=4 /COL=6 & /FACILITY=ORDER_PRINT ITEM_BLOCK EXIT /ROW=11 /COL=6 & /FACILITY=EXIT END_FORM

Forms and Form Qualifiers IAF 8.0 DML

3-11

NORMAL Forms

NORMAL Forms
General Purpose
NORMAL forms facilitate general fixed-format screen input and output, and are especially useful for single record updates. NORMAL forms always have screen output. Therefore, the inclusion of form placement qualifiers is mandatory. These qualifiers specify where IAF is to display the forms window on the screen.

Form Header Statement Syntax

Following is the syntax for the FORM statement, which is the form header statement to use for NORMAL forms:
FORM form_name [(argument1[,argument2[,...]])] & /ROW=numeric_expression & /COL=numeric_expression & /HEIGHT=numeric_expression & /WIDTH=numeric_expression [/qualifiers]

3-12

Forms and Form Qualifiers IAF 8.0 DML

NORMAL Forms

Implicit Form Actions

When executing a NORMAL form, IAF pastes the forms window on the screen and displays in it all the forms input and output blocks in their clean state. The FORM statements mandatory /HEIGHT and /WIDTH qualifiers govern the size of the form window, and the FORM statements mandatory /ROW and /COL qualifiers govern the placement of the window on the screen. IAF then executes the forms DML code (including any branching or GOTO statements). After executing the DML code, IAF unpastes the form window from the screen as the NORMAL form exits. For details regarding input and output blocks, refer to this manuals BLOCKS AND BLOCK QUALIFIERS chapter. Given the fact that Row 2 is the top border of the outer form, iBrowser and IAF Mobile use it for the button bar. The title of an outer form is displayed on the button bar. The outer form displays no border (except for the top border which is the button bar). An outer form is recognized with the following characteristics: FORM form_name/ROW=3/COL=2/HEIGHT=21/WIDTH=78 Any form with a border that is not the outer form and starts in Row 3 will have its top border (or title bar) covered by the button bar. A form with a row less than 3 is not valid.

Forms and Form Qualifiers IAF 8.0 DML

3-13

NORMAL Forms

Applicable Qualifiers
The following qualifiers are applicable to the FORM statement. For details regarding these qualifiers, refer to this chapters Form Qualifiers section.
/ATTRIBUTES/FIRST/NOEXIT_FORWARD/ROW/STREAM_NAME /BASE/GROUPED_BY/READ_ONLY/SECONDARY/TABLE /BREAK/HEIGHT/REDUCED_TO/SELECTION/TITLE /BREAK0/JOINED_TO/REMAIN/SORTED_BY/WIDTH /COL/LOCK/REPEAT/STATISTIC/WITH

Example
FORM MAIN /ROW=3 /COL=2 /HEIGHT=20 /WIDTH=78 /REPEAT ! This form modifies a warehouse name. The form repeats ! until an explicit exit takes place or a back action takes !place at the first input block. INPUT_BLOCK WAREHOUSE_CODE /ROW=2 /COL=40 & /PROMPT=FIELD_PROMPT(WAREHOUSE_CODE) & /TARGET=WAREHOUSES(WAREHOUSE_CODE) ! This input block prompts for and retrieves a ! warehouse ! code. Because WAREHOUSE_CODE is the primary ! identifier (PID) for the WAREHOUSES table, ! IAF ! performs a lookup to ensure that a warehouse ! with the ! given code exists. INPUT_BLOCK NAME /ROW=4 /COL=40 & /PROMPT=FIELD_PROMPT(NAME) & /TARGET=WAREHOUSES(NAME) ! Display the warehouse name and allow the end user ! to update it. YESNO_BLOCK /ROW=6 /COL=40 & /PROMPT=Correct & /FAILURE=(CONTINUE ROLLBACK) ! Prompt the end user for verification that the ! modification should take place. If the end user ! indicates that the modification should not take ! place, rollback the update.

END_FORM

3-14

Forms and Form Qualifiers IAF 8.0 DML

PROCEDURE Forms

PROCEDURE Forms
General Purpose
PROCEDURE forms facilitate data processing that requires little or no screen interaction, and are ideal for performing table updates and data transfers. A PROCEDURE form can perform DML code that requires input and/or output relative to a parent form. For example, a REPORT form (the parent form) may call a PROCEDURE form to calculate and print totals on a specified level break in the report. In this situation, the PROCEDURE forms output blocks, which print the totals, must have explicit /ROW and /COL qualifiers relative to the REPORT form. For details regarding output blocks, refer to this manuals BLOCKS AND BLOCK QUALIFIERS chapter.

Form Header Statement Syntax

Following is the syntax for the PROCEDURE_FORM statement, which is the form header statement to use for PROCEDURE forms:
PROCEDURE_FORM form_name [(argument1[,argument2[,...]])] [/qualifiers]

Implicit Form Actions

When executing PROCEDURE forms, IAF does not paste a form window on the screen. Any PROCEDURE form screen interaction occurs in the form window of the parent form. Unlike other form types, PROCEDURE forms do not have any implicit action.

Forms and Form Qualifiers IAF 8.0 DML

3-15

PROCEDURE Forms

Applicable Qualifiers
The following qualifiers are applicable to the PROCEDURE_FORM statement. For details regarding these qualifiers, refer to this chapters Form Qualifiers section.
/BASE/LOCK/STATISTICS /BREAK/NOEXIT_FORWARD/STATUS /BREAK0/READ_ONLY/STREAM_NAME /COMMIT_RATE/REDUCED_TO/TABLE /FIRST/SECONDARY/WITH /GROUPED_BY/SELECTION /JOINED_TO/SORTED_BY

Example:
PROCEDURE_FORM MAIN /TABLE=SALES_ORDERS /WITH=DEPARTMENT=COM ! Select all SALES_ORDERS table records having a ! department ID of COM. SALES_ORDERS (SALES_PERSON)= ! Remove all salesperson IDs from these records. END_FORM

3-16

Forms and Form Qualifiers IAF 8.0 DML

QUERY Forms

QUERY Forms
General Purpose
QUERY forms facilitate performing inquiries on and maintaining records in tables. QUERY forms have a variety of modes. FIND and DISPLAY modes enable end users to view records for which they have specified record selection criteria. INSERT mode allows end users to add new records to tables. MODIFY and DELETE modes enable end users to update and delete records, respectively, selected via FIND mode.

Form Header Statement Syntax

Following is the syntax for the QUERY_FORM statement, which is the form header statement to use for QUERY forms:
QUERY_FORM form_name [(argument1[,argument2[,...]])]& /ROW=numeric_expression & /COL=numeric_expression & /HEIGHT=numeric_expression & /WIDTH=numeric_expression & /TABLE=table_name [/qualifiers]

Implicit Form Actions

When executing a QUERY form, IAF pastes the forms window on the screen and displays in it all the forms input and output blocks in their clean state. The QUERY_FORM statements mandatory /HEIGHT and /WIDTH qualifiers govern the size of the form window, and the QUERY_FORM statements mandatory /ROW and /COL qualifiers govern the placement of the window on the screen. Sometimes, IAF dictates a QUERY forms mode. For example, IAF initially places the QUERY form into FIND mode to enable the end user to specify record selection criteria via the forms input blocks. After executing FIND mode, IAF places the QUERY form into DISPLAY mode. However, more often, the end user dictates the QUERY forms mode.

Forms and Form Qualifiers IAF 8.0 DML

3-17

QUERY Forms

The following table lists and describes the keys that enable the end user to switch from one QUERY form mode to another. Key GM_DELETE_ROW GM_FIND_ROW GM_INSERT_ROW GM_SELECT_ROW Effect This key activates DELETE mode to facilitate deleting records. This key activates FIND mode to facilitate specifying record selection criteria. This key activates INSERT mode to facilitate adding new records. This key activates MODIFY mode to facilitate updating the current record.

It is possible to change modes by executing one of several EXIT statement types in an alternate form (a form that the QUERY_FORM statements /ADD_FORM, /DELETE_FORM, /FIND_FORM, or /MODIFY_FORM qualifier specifies). The table on the following page lists and describes these statements. EXIT Statement EXIT (%ADD) EXIT (%DELETE) EXIT (%DISPLAY) EXIT (%FIND) EXIT (%MODIFY) Effect Switches to INSERT mode. Switches to DELETE mode. Switches to DISPLAY mode. Switches to FIND mode. Switches to MODIFY mode.

A QUERY forms current mode is available in the %EDIT_MODE special variable. Its value can be %ADD (INSERT mode), %DELETE (DELETE mode), %MODIFY (MODIFY mode), %DISPLAY (DISPLAY mode), or %FIND (FIND mode). Note: Comparing against %DELETE in a QUERY form will not give you your desired results since control is not returned back to the DML code when the delete key is pressed. What you should do is define an alternate form, and withinthat form, compare %EDIT_MODE against %DELETE. You could also define a delete form for the QUERY form.

3-18

Forms and Form Qualifiers IAF 8.0 DML

QUERY Forms

The following table lists and describes special variables that contain information that IAF displays on QUERY forms. Special Variable %QUERY_MODE Description This special variable contains the description of the current mode. NOTE: Do not use %QUERY_MODE to test for the current mode. The description that this variable contains may change from language to language. To test for the current mode, use the %EDIT_MODE special variable. This special variable contains a value indicating the number of records selected via the last FIND query. This special variable contains a value indicating the number of the current record (relative to the number of records selected via the last FIND query).

%QUERY_MAX_RE C %QUERY_CUR_REC

When an end user enters record selection criteria in FIND mode, IAF searches for records for which the criteria is true. The criteria can be simple data, data with wildcard characters, or data preceded by an operator. If the end user presses the GM_SELECT_MODE key in FIND mode, the current field becomes a multiple input window. A multiple input window facilitates entering a range of data and/or multiple data values as the selection criteria upon which the QUERY forms record selection process is to operate. The rules for entering selection criteria in a QUERY form are the same as those for entering selection criteria in IAFs Query By Forms utility. For details on entering selection criteria in a QUERY form, refer to the description of the Query By Forms utility in the IAF System Reference Manual. Upon locating the set of records for which entered selection criteria is true, IAF displays the sets first record in the QUERY form. The end user can view individual records in the set by using the GM_NEXT_SCREEN key to move forward in the set and the GM_PREV_SCREEN key to move backward. To limit the number of records that IAF selects for a QUERY form, use the QUERY_FORM statements /FIRST qualifier or the GEM_SELECT_LIMIT system customization variable (SCV). For details on /FIRST, refer to this chapters Form Qualifiers section. For details on

Forms and Form Qualifiers IAF 8.0 DML

3-19

QUERY Forms

GEM_SELECT_LIMIT, refer to the IAF guide that applies to your operating system. IAF maintains transaction control for QUERY forms on a record-byrecord basis. A transaction starts when an end user selects a record to modify or delete, or begins inserting a record. The transaction rolls back if the end user changes modes or does not exit the current mode via the GM_EXIT_FORWARD key. The transaction commits if the end user uses the GM_EXIT_FORWARD key to exit the current mode. This is true only for actual transactions (not for pseudo transactions). For details regarding transactions, refer to the IAF Users Guide. A QUERY form can include DML code. However, the code does not execute while the form is in DISPLAY mode unless the code is in a DML block that specifies the /DISPLAY_ONLY qualifier. For details on DML blocks and the /DISPLAY_ONLY qualifier, refer to this manuals BLOCKS AND BLOCK QUALIFIERS chapter. When a QUERY form exits, it must exit via an explicit exit forward condition for the current mode to execute. An exit forward condition occurs when the form exits via the GM_EXIT_FORWARD key or an explicit DML EXIT(%EXIT_FORWARD) statement.

Applicable Qualifiers
The following qualifiers are applicable to the QUERY_FORM statement. For details regarding these qualifiers, refer to this chapters Form Qualifiers section.
/ADD_FORM /ATTRIBUTES /BASE /SELECTION /READ_ONLY /TABLE /FIND_FORM /FIRST /HEIGHT /WITH /SORTED_BY /MODIFY_FORM /REMAIN/TITLE

/NOEXIT_FORWARD /ROW/WIDTH /OPTIONS /COL /DELETE_FORM /PDF /JOINED_TO /LOCK/REDUCED_TO

3-20

Forms and Form Qualifiers IAF 8.0 DML

QUERY Forms

Example:
QUERY_FORM MAIN /ROW=3 /COL=2 /HEIGHT=21 /WIDTH=78 & /TABLE=CUSTOMERS /TITLE=(Maintain Customers) OUTPUT_BLOCK MODE /ROW=1 /COL=10 /LEN=10 & /PROMPT=Mode: /SOURCE=(%QUERY_MODE) OUTPUT_BLOCK CUR_REC /ROW=1 /COL=60 /LEN=5 & /PROMPT=Record: /SOURCE=(%QUERY_CUR_REC) OUTPUT_BLOCK MAX_REC /ROW=1 /COL=70 /LEN=5 & /PROMPT= of /SOURCE=(%QUERY_MAX_REC) INPUT_BLOCK IDENT /ROW=3 /COL=35 /NEW & /PROMPT=(FIELD_PROMPT(IDENT)) /TARGET=CUSTOMERS(IDENT) ! Because /NEW is present, and the target table field ! is the CUSTOMERS tables PID, the QUERY form ! requests input for it only in FIND and INSERT modes. INPUT_BLOCK NAME /ROW=4 /COL=35 & /PROMPT=(FIELD_PROMPT(NAME)) /TARGET=CUSTOMERS(NAME) INPUT_BLOCK AGE /ROW=5 /COL=35 & /PROMPT=(FIELD_PROMPT(AGE)) /TARGET=CUSTOMERS(AGE) INPUT_BLOCK SALARY /ROW=6 /COL=35 &
/PROMPT=(FIELD_PROMPT(SALARY)) /TARGET=CUSTOMERS(SALARY)

INPUT_BLOCK REMARKS /ROW=7 /COL=35 & /PROMPT=(FIELD_PROMPT(REMARKS)) /TARGET=CUSTOMERS(REMARKS) INPUT_BLOCK PHONE /ROW=8 /COL=35 & /PROMPT=(FIELD_PROMPT(PHONE)) /TARGET=CUSTOMERS(PHONE) EXIT (%EXIT_FORWARD) END_FORM

Forms and Form Qualifiers IAF 8.0 DML

3-21

REPORT Forms

REPORT Forms
General Purpose
REPORT forms facilitate defining report formats. The blocks within a REPORT form describe the format IAF is to use to write a selected set of records to a disk file. REPORT forms do not permit any screen input or output.

Form Header Statement Syntax

Following is the syntax for the REPORT_FORM statement, which is the form header statement to use for REPORT forms:
REPORT_FORM form_name [(argument1[,argument2[,...]])] & /TABLE=table_name [/qualifiers]

Implicit Form Actions

When executing a REPORT form, IAF opens a report file and assigns to it the name that the REPORT_FORM statements /OUTPUT qualifier specifies, if present. If no /OUTPUT qualifier is present, IAF constructs a default filename. IAF selects a set of records for the report based upon the record selection criteria that the REPORT_FORM statement specifies. Then, IAF performs the body of the form once per record in the record order that the selection criteria specifies, and directs all output to the report file.

3-22

Forms and Form Qualifiers IAF 8.0 DML

REPORT Forms

Applicable Qualifiers
The following qualifiers are applicable to the REPORT_FORM statement. For details regarding these qualifiers, refer to this chapters Form Qualifiers section.
/BASE/HEADING_FORM/RFOOTING /BEGIN_ROW/HEIGHT/RHEADING /BREAK/JOINED_TO/SECONDARY /BREAK0/LFOOTING/SELECTION /COLUMN_HEADINGS/LHEADING/SORTED_BY /COLUMN_SPACING/LINES_AFTER/STATISTIC /END_ROW/LINES_BEFORE/STATUS /FIND_FORM/LOCK/STREAM_NAME /FIRST/NOSTATUS/TABLE /FOOTING/OPTIONS/WIDTH /FOOTING_FORM/OUTPUT/WITH /PDF /GROUPED_BY/READ_ONLY /HEADING/REDUCED_TO

Example:
REPORT_FORM MAIN & /TABLE=WAREHOUSES & /SORTED_BY=NAME & /HEADING=(%TODAY) & /RHEADING=(MASK (PAGE @@@@, % PAGE)) & /HEADING=WAREHOUSE REPORT OUTPUT_BLOCK WAREHOUSE & /SOURCE=WAREHOUSES(WAREHOUSE) OUTPUT_BLOCK NAME & /SOURCE=WAREHOUSES(NAME) /PDF=(option=value[, option=value[,...]]) END_FORM

Forms and Form Qualifiers IAF 8.0 DML

3-23

TABLE_EDIT Forms

TABLE_EDIT Forms
General Purpose
TABLE_EDIT forms facilitate viewing and/or editing a set of records selected from one or more tables. IAF displays the selected records in a scrolling window on the screen. Typically, TABLE_EDIT forms are used to accommodate record inquiries on tables that contain large numbers of records. For example, you could use a TABLE_EDIT form to perform a sales order inquiry to view only the orders that a particular customer placed. TABLE_EDIT forms also facilitate inputting and editing record data. For example, you could use a TABLE_EDIT form to enter new sales order detail records or modify existing ones. The blocks that reside within a TABLE_EDIT form determine the form windows input and/or output.

Form Header Statement Syntax

Following is the syntax for the TABLE_FORM statement, which is the form header statement to use for TABLE_EDIT forms:
TABLE_FORM form_name [(argument1[,argument2[,...]])] & /ROW=numeric_expression & /COL=numeric_expression & /HEIGHT=numeric_expression & /WIDTH=numeric_expression & /TABLE=table_name [/qualifiers]

Implicit Form Actions

When executing a TABLE_EDIT form, IAF selects the set of records that the TABLE_FORM statements mandatory /TABLE qualifier specifies, and then pastes the forms window on the screen. The TABLE_FORM statements mandatory /HEIGHT and /WIDTH qualifiers govern the size of the form window, and the TABLE_FORM statements mandatory /ROW and /COL qualifiers govern the placement of the window on the screen. By default, IAF allots one TABLE_EDIT form screen row per selected record. IAF displays as many rows as it can in the form window without exceeding the specified height of the window. To do this, IAF loads each record in turn into the user buffer, sets the display start row to one row

3-24

Forms and Form Qualifiers IAF 8.0 DML

TABLE_EDIT Forms

below the last start row, and performs one of the operations that the following table lists according to form type. Form Type Read/Write Operation IAF imposes an implicit DISPLAY DEFAULTS condition on the form. This causes the record data in the user buffer to appear as the default for the blocks in the TABLE_EDIT form. A TABLE_EDIT form is read/write if the given TABLE_FORM statement does not include either the /READ_ONLY qualifier or the /MENU qualifier. IAF performs the forms DML code. A TABLE_EDIT form is read-only if the given TABLE_FORM statement includes either the /READ_ONLY qualifier or the /MENU qualifier.

Read-only

Via the TABLE_FORM statements /ROW_HEIGHT qualifier, it is possible to specify the number of screen rows to allot to each selected record. Additionally, it is possible to limit the number of records that IAF selects for a TABLE_EDIT form. To do this, use the TABLE_FORM statements /FIRST qualifier or the GEM_SELECT_LIMIT system customization variable (SCV). For details on /FIRST, refer to this chapters Form Qualifiers section. For details on GEM_SELECT_LIMIT, refer to the IAF guide that applies to your operating system. After IAF displays the selected records in the TABLE_EDIT forms window, the end user can scroll through the record set one line at a time by using the GM_UP key to move forward in the set and the GM_DOWN key to move backward. The end user can view the first record of the set by using the GM_PREV_SCREEN key, and can view the last record of the set by using the GM_NEXT_SCREEN key. The following table lists and describes the keys that facilitate record addition and maintenance operations within TABLE_EDIT forms. Key GM_DELETE_ROW Effect This key deletes the record upon whose row the cursor is currently positioned. IAF does not allow record deletions to take place in a TABLE_EDIT form that operates on more than one table (as a result of specifying more than one table in the record selection criteria.)

Forms and Form Qualifiers IAF 8.0 DML

3-25

TABLE_EDIT Forms

Key GM_FIND_ROW

Effect This key allows the end user to enter record selection criteria if a find form is specified via the TABLE_FORM statements /FIND_FORM qualifier. The criteria can be simple data, data with wildcard characters, or data preceded by an operator. The rules for entering selection criteria in a TABLE_EDIT form are the same as those for entering selection criteria in IAFs Table Editor utility. For details on entering selection criteria in a TABLE_EDIT form, refer to the description of the Table Editor utility in the IAF System Reference Manual. This key allows the end user to add a record to the given table in the position in which the cursor is currently located. When the end user presses GM_INSERT_ROW, IAF clears the data buffer and performs the forms DML code. If the form allots more than one screen line to each record (as a result of using the /ROW_HEIGHT qualifier) the input area expands to the specified number of screen lines. Upon completely executing the forms DML code, IAF adds the new record to the table if the end user does not exit the insert form first via the GM_BACK or GM_EXIT key. Note that a read-only TABLE_EDIT form does not allow the end user to insert new record data. Also note that IAF does not allow record insertions to take place in a TABLE_EDIT form that operates on more than one table (as a result of specifying more than one table in the record selection criteria.)

GM_INSERT_ROW

3-26

Forms and Form Qualifiers IAF 8.0 DML

TABLE_EDIT Forms

Key GM_SELECT_ROW

Effect This key selects the record upon whose row the cursor is currently located to allow the end user to modify the record. IAF loads the record into the user buffer and performs the TABLE_EDIT forms DML code. If the selected row consists of more than one screen line (as a result of using the /ROW_HEIGHT qualifier) the input area expands to the specified number of screen lines. Note that a TABLE_EDIT form does not request input for PID fields during record modifications. Also note that a read-only TABLE_EDIT form does not allow the end user to select a row of record data unless an alternate form is specified via the TABLE_FORM statements /ALTERNATE_FORM qualifier.

When a TABLE_EDIT form exit takes place, IAF unpastes the form window from the screen.

Forms and Form Qualifiers IAF 8.0 DML

3-27

TABLE_EDIT Forms

Applicable Qualifiers
The following qualifiers are applicable to the TABLE_FORM statement. For details regarding these qualifies, refer to this chapters Form Qualifiers section.
/ALTERNATE_FORM /ATTRIBUTES /BASE /BEGIN_ROW /COL /FIND_FORM /FIRST /HEIGHT /OPTIONS/SEQUENCE /READ_ONLY/SEQUENCE_INCREMENT /REDUCED_TO/SORTED_BY

/INPUT_ROW_HEIGHT /REMAIN/TABLE /JOINED_TO /ROW/TITLE /ROW_HEIGHT/WIDTH /SECONDARY/WITH /SELECTION

/COLUMN_HEADING_ROW /LOCK /DELETE_FORM /END_ROW /NOERROR /NOEXIT_FORWARD

Example
TABLE_FORM MAIN /ROW=3 /COL=2 /HEIGHT=20 /WIDTH=78 & /OPTIONS=NODELETE, NOINSERT & /TABLE=WAREHOUSES ! This form displays records from the WAREHOUSES table ! and allows the end user to select and modify the dis ! played ! records. This form does not allow the end user to add or ! delete records. INPUT_BLOCK WAREHOUSE_CODE /ROW=1 /COL=2 & /TARGET=WAREHOUSES(WAREHOUSE_CODE) ! This block acts only as a display block (updating ! PIDs is not allowed). INPUT_BLOCK NAME /ROW=1 /COL=20 & /TARGET=WAREHOUSES(NAME) ! This block displays the warehouse name for the ! given record, and allows the warehouse name to be ! updated. END_FORM

3-28

Forms and Form Qualifiers IAF 8.0 DML

Form Qualifiers

Form Qualifiers
A form qualifier represents an option that you can activate by appending the qualifier to a form header statement to which it applies. The following table lists all form qualifiers in alphabetical order, and indicates the form type(s) to which each qualifier applies. The table contains a column for each form type. If the column contains an X where a given qualifier row and form type column intersect, the qualifier applies to that form type. The table uses the following form type codes to mark the form type columns:
N=NORMAL T=TABLE_EDIT Q=QUERY R=REPORT M=MENU P=PROCEDURE

Immediately following this table are detailed descriptions of these qualifiers, also presented in alphabetical order by qualifier name. Form Qualifiers N /ADD_FORM /ALTERNATE_FORM /ATTRIBUTES /BASE /BEGIN_ROW /BREAK /BREAK0 /COL /COLUMN_HEADINGS /COLUMN_HEADING_ROW /COLUMN_SPACING X X X X X X X X X X X X X X X X X X X X X X X X X Applicable Form Type T Q X R M P

Forms and Form Qualifiers IAF 8.0 DML

3-29

Form Qualifiers

Form Qualifiers N /COMMIT_RATE /DEFAULT_TAG /DELETE_FORM /END_ROW /FIND_FORM /FIRST /FOOTING /FOOTING_FORM /GROUPED_BY /HEADING /HEADING_FORM /HEIGHT /INPUT_ROW_HEIGHT /JOINED_TO /LFOOTING /LHEADING /LINES_AFTER /LINES_BEFORE /LOCK /MODIFY_FORM /NOERROR /NOEXIT_FORWARD /NOSTATUS /OPTIONS /OUTPUT X X X X X X

Applicable Form Type T Q R M P X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X

3-30

Forms and Form Qualifiers IAF 8.0 DML

Form Qualifiers

Form Qualifiers N /PDF /READ_ONLY /REDUCED_TO /REMAIN /REPEAT /RFOOTING /RHEADING /ROW /ROW_HEIGHT /SECONDARY /SELECTION /SEQUENCE /SEQUENCE_INCREMENT /SORTED_BY /STATISTIC /STATUS /STREAM_NAME /SYSTEM /TABLE /TAG_LENGTH /TITLE /WIDTH /WITH X X X X X X X X X X X X X X

Applicable Form Type T Q R X X X X X X X X X X X X M P

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X

This qualifier dictates the size of the printed page, not the screens display area.

Forms and Form Qualifiers IAF 8.0 DML

3-31

Form Qualifiers

The remainder of this section provides detailed descriptions of the qualifiers that apply to one or more form header statements. Unless stated otherwise, each qualifier is applicable only once to a given form header statement. For details on a particular form header statement and the qualifiers that apply to it, refer to this chapters section pertaining to that form type (MENU, NORMAL, PROCEDURE, QUERY, REPORT, or TABLE_EDIT). Note that the given qualifier examples do not necessarily include the other qualifiers (/ROW, /COL, and so on) that the given form header statement requires.

3-32

Forms and Form Qualifiers IAF 8.0 DML

/ADD_FORM

/ADD_FORM
Syntax
/ADD_FORM=form_name

Description
This qualifier allows you to specify an alternate form to execute in place of the standard insert form when an end user enters INSERT mode via the GM_INSERT_ROW key to add a record in a QUERY form. The specified form must exist in the current compilation unit. In order for the QUERY form to add the record, the alternate form must exit under an explicit exit forward condition. This condition occurs if the end user exits the form via the GM_EXIT_FORWARD key or a DML EXIT(%EXIT_FORWARD) statement executes. For details regarding the EXIT statement, refer to this manuals LANGUAGE STATEMENTS chapter.

Example
/ADD_FORM=NEW_ORDER

Forms and Form Qualifiers IAF 8.0 DML

3-33

/ALTERNATE_FORM

/ALTERNATE_FORM
Syntax
/ALTERNATE_FORM=form_name

Description
This qualifier allows you to specify an alternate form to execute when an end user adds or modifies records in a TABLE_EDIT form via the GM_INSERT_ROW key or GM_SELECT_ROW key, respectively. For example, suppose all update fields do not fit across a single screen. Via the /ALTERNATE_FORM qualifier, you can specify a form that displays update fields (for a single record) down the screens length rather than across its width. The %EDIT_MODE special variable facilitates testing an alternate forms current mode. When you use %EDIT_MODE in this manner, its value is either %ADD or %MODIFY. For details on %EDIT_MODE and other special variables, refer to this manuals SPECIAL VARIABLES AND VALUE SYMBOLS chapter.

Example
/ALTERNATE_FORM=MAINTAIN_EMPLOYEES

3-34

Forms and Form Qualifiers IAF 8.0 DML

/ATTRIBUTES

/ATTRIBUTES
Syntax
/ATTRIBUTES=keyword[,keyword[,...]]

Description
This qualifier allows you to specify the default display attributes for a form window. You can specify any combination of attribute keywords. However, you may not use any keyword more than once. The following table lists and describes the effects of the attribute keywords that are valid for use with this qualifier. Keyword BLINK BOLD NOBORDE R All characters blink. All characters display in bold. No window border displays (by default, NORMAL, QUERY, and TABLE_EDIT forms implicitly create screen windows having borders.) A forms title displays even if the form has no border. To provide for a title on a form without a border, IAF simulates a blank border via a background window that is higher by two rows and wider by two columns, upon which it places the title. All characters display in reverse video. All characters are underlined. Effect

REVERSE UNDERLI NE

Example
TABLE_FORM MAIN /ROW=3 /COL=2 & /TITLE=Add New Employees & /TABLE=EMPLOYEES & /ATTRIBUTES=BOLD,REVERSE

Forms and Form Qualifiers IAF 8.0 DML

3-35

/BASE

/BASE
Syntax
/BASE

Description
When IAF executes the DML SWITCH_BASE form_name statement, IAF searches backward through all the forms that have executed in the current session until it encounters the first form whose form header statement includes the /BASE qualifier. Upon locating the first form specifying the /BASE qualifier, IAF performs the form that the SWITCH_BASE statement specifies. The form executes within the context of the calling form (the form with the /BASE qualifier). This happens because IAF exits the form that contains the SWITCH_BASE statement, and any other calling forms, until it finds a form whose form header statement includes the /BASE qualifier. For details regarding the SWITCH_BASE statement, refer to this manuals Language Statements chapter.

3-36

Forms and Form Qualifiers IAF 8.0 DML

/BEGIN_ROW

/BEGIN_ROW
Syntax
/BEGIN_ROW=numeric_expression

Description
This qualifier applies to REPORT forms and TABLE_EDIT forms.

For REPORT forms:

This qualifier allows you to specify the row upon which the detail lines in a REPORT form are to start printing. IAF positions any column headings one row above the row that this qualifier specifies. If a given REPORT_FORM statement does not include the /BEGIN_ROW qualifier, IAF begins printing the reports detail lines on the row following the column headings.

For TABLE_EDIT forms:

This qualifier allows you to specify the row upon which selected records in a TABLE_EDIT forms window are to begin displaying. The default start row is either the first row after the last text declaration, or the row after the row that the /COLUMN_HEADING_ROW qualifier specifies. The /BEGIN_ROW qualifier, in conjunction with the /END_ROW qualifier, allows you to force a TABLE_EDIT form to display before any TEXT declaration(s) on the form. For details regarding the /COLUMN_HEADING_ROW and /END_ROW qualifiers, refer to their descriptions in this section. For details regarding TEXT declarations, refer to this manuals FIXED DISPLAY DECLARATIONS chapter.

Examples
/BEGIN_ROW=12 /BEGIN_ROW=#FIRST_LINE

Forms and Form Qualifiers IAF 8.0 DML

3-37

/BREAK

/BREAK
Syntax
/BREAK=begin_form_name,[end_form_name],break_expression or /BREAK=[end_form_name,]break_expression or /BREAK=begin_form_name,[break_option[,break_option[,...]]],break_expressio
n

or /BREAK=[break_option[,break_option[,...]]]break_expression

Description
The /BREAK qualifier allows you to specify a level break on a form that processes records. A form header statement may include as many as 20 /BREAK qualifiers. A level break indicates that a break is to occur in the record processing sequence when the value of a specific entity (field) changes. During that break, IAF performs a specified action. For example, a level break can sub-total columns in a report, or print totals at the end of the report. Following are the components of a level break specification:

break_expression
This is a DML expression that IAF evaluates for each record in the set. The expression triggers a level break when the evaluated value changes. For example, you might specify CUSTOMERS(CUSTOMER_REGION) as the break expression to trigger a level break when that table fields value changes.

begin_form_name
This is the name of a form that IAF is to execute before a new level break begins. Typically, the begin level break form resets level break totals to zero.

end_form_name
This is the name of the form that IAF is to execute at the end of the level break. Note that the record that is available to the end level break form is the last record in the break set. Typically, the end level break form outputs or stores the totals for a given level break.

3-38

Forms and Form Qualifiers IAF 8.0 DML

/BREAK

break_option[,break_option[,...]]
This is one or more report break options. Break options facilitate changing a report break totals format. All break option keywords begin with a percent (%) sign. The following table lists and describes the break option keywords that are valid for use with the /BREAK qualifier on a REPORT form. Report Break Options Keyword %BOTTOM_LINE=string_expression Effect This option causes a line of separator characters to print below the total values on a report. The first character of the given expression is the separator character to use. This option causes the %TEXT expression to print starting in the report column that the given numeric expression indicates. By default, the expression starts to print in column one of the totals row. This option specifies the name of a form to execute for the given level break. The form executes after the %TEXT string expression prints. The given form must exist in the current compilation unit. This option inserts the given number of blank lines after the reports totals.

%COL=numeric_expression

%FORM=form_name

%LINES_AFTER=numeric_expression

Forms and Form Qualifiers IAF 8.0 DML

3-39

/BREAK

Report Break Options Keyword %LINES_AFTER=TOP_OF_PAGE Effect This option causes a page break to occur after the reports totals print. This option inserts the given number of blank lines before the reports totals. This option causes a page break to occur before the reports totals print. This option suppresses the printing of totals for the given level break. This option suppresses the printing of the underline which, by default, prints between the last detail line and the total line in a report. This option causes the %TEXT expression to print starting on the report row that the given numeric expression indicates. By default, the expression prints on the same row as the reports totals.

%LINES_BEFORE=numeric_expression

%LINES_BEFORE=TOP_OF_PAGE

%NOTOTALS

%NOUNDERLINES

%ROW=numeric_expression

3-40

Forms and Form Qualifiers IAF 8.0 DML

/BREAK

Report Break Options Keyword %TEXT=string_expression Effect This option specifies a string expression which, by default, is to start printing in the reports first column on the totals row. To change the location in which the expression prints, use the %ROW option and/or the %COLUMN option. This option specifies a replacement character for the - character of which a line prints between the detail line and the total line on a report. The first character of the given expression is the replacement character to use. This option suppresses the printing of a total line if the detail set consists of only one member. In a situation where there is only one member in a detail set, its value is same as the total. Therefore, printing the total line is redundant.

%TOP_LINE=character_expression

%TSUPPRESS

Forms and Form Qualifiers IAF 8.0 DML

3-41

/BREAK

The order of the specified /BREAK qualifiers is important. The first /BREAK qualifier should specify the most significant break in the record set that the form is processing. The second and subsequent /BREAK qualifiers should specify breaks having less significance (in descending significance order) in the record set. For example, to present a geographic break-down of all customers, you might specify the following level breaks:
/BREAK=CUSTOMERS(CUSTOMER_REGION) /BREAK=CUSTOMERS(STATE) /BREAK=CUSTOMERS(CITY)

In this example, level break one occurs when the CUSTOMER_REGION fields value changes. Level break two occurs when the STATE fields value changes. Level break three occurs when the CITY fields value changes. IAF refers to level breaks by their relative numbers. In the preceding example, the level break on the CUSTOMERS(CUSTOMERS_REGION) table field is break 1, the level break on the CUSTOMERS(STATE) table field is break 2, and so on. Therefore, changing the order of existing level breaks, or inserting new level breaks between existing ones changes the relative numbers of some or all level breaks. This is noteworthy because the blocks in a form can reference relative break numbers. For information on how blocks reference relative break numbers, refer to this manuals BLOCKS AND BLOCK QUALIFIERS chapter.

Examples
/BREAK=START_DEPT,FINISH_DEPT,ORDERS(DEPARTMENT)

This qualifier specifies that a level break is to occur on the ORDERS(DEPARTMENT) table field. It also indicates that the begin and end break forms are the START_DEPT and FINISH_DEPT forms, respectively.
/BREAK=CUSTOMER_HEADER,,ORDERS(CUSTOMER_ID)

This qualifier specifies that a level break is to occur on the ORDERS(CUSTOMERS_ID) table field. It also indicates that the begin break form is the CUSTOMER_HEADER form.
/BREAK=ORDERS(CUSTOMER_ID)

This qualifier specifies that a level break is to occur on the ORDERS(CUSTOMER_ID) table field.
/BREAK=SKIP_LINES,ORDERS(CUSTOMER_ID)

3-42

Forms and Form Qualifiers IAF 8.0 DML

/BREAK

This qualifier specifies that a level break is to occur on the ORDERS(CUSTOMER_ID) table field. It also specifies that the end break form is the SKIP_LINES form.
REPORT_FORM MAIN & /OUTPUT=ABC & /TABLE=CUSTOMERS & /SORTED_BY=DEPARTMENT &
/BREAK=%TEXT=(Total for department & CUSTOMERS(DEPARTMENT)), &

%TOP_LINE==, & %LINES_AFTER=1, & (CUSTOMERS(DEPARTMENT))

This qualifier specifies that a level break is to occur on the CUSTOMERS(DEPARTMENT) table field. The %TEXT option causes Total for department to print to the left of each break total line. The %TOP_LINE option causes the equal character (=) to print before each break total line, and the %LINES_AFTER option inserts a single line after each level break.

Forms and Form Qualifiers IAF 8.0 DML

3-43

/BREAK0

/BREAK0
Syntax
/BREAK0=[before_form_name][,after_form_name] or /BREAK0=[begin_form][,break_option[,break_option[,...]]]

Description
This qualifier allows you to specify a form to execute prior to the current form (the form whose form header statement includes this qualifier), and/or a form to execute after the current form. To use this qualifier, the given form header statement must specify record selection criteria (it must include the /TABLE form qualifier at the very least). The /BREAK0 qualifier causes a zero level break to occur when the record loop starts and when it ends. REPORT forms can use /BREAK0 qualifiers to specify begin forms to display note pages. Likewise, REPORT forms can use /BREAK0 qualifiers to specify end forms to display grand totals, thereby overriding totals resulting from use of the /TOTAL block qualifier. For details on the /TOTAL block qualifier, refer to this manuals BLOCKS AND BLOCK QUALIFIERS chapter. REPORT forms can also use report break option keywords with the /BREAK0 qualifier. For details on report break option keywords, refer to this chapters description of the /BREAK qualifier.

Examples
/BREAK0=NOTES,GRAND_TOTALS

This qualifier specifies that IAF is to execute the NOTES form before the current form, and the GRAND_TOTALS form after the current form.
/BREAK0=TOP

This qualifier specifies that IAF is to execute the TOP form before the current form.
/BREAK0=,DONE

This qualifier specifies that IAF is to execute the DONE form after the current form.

3-44

Forms and Form Qualifiers IAF 8.0 DML

/CHEADING

/CHEADING
Syntax
/CHEADING=expression

Description
/CHEADING displays the complete handling text centered with the column. In case there is not enough space for the text it will omit the heading. This affects display in iBrowser as well.

Forms and Form Qualifiers IAF 8.0 DML

3-45

/COL

/COL
Syntax
/COL=numeric_expression

Description
This qualifier allows you to specify the screen column that is to be the first column of the current forms window, and is mandatory for NORMAL, TABLE_EDIT, QUERY, and MENU forms.

Examples
/COL=2 /COL=#NEW_COL /COL=(#MAX_COLS/2)

3-46

Forms and Form Qualifiers IAF 8.0 DML

/COLUMN_HEADINGS

/COLUMN_HEADINGS
Syntax
/COLUMN_HEADINGS=form_name

Description
This qualifier allows you to specify the name of a form that contains the column headings a REPORT form is to use. The headings in the specified form override any headings that IAF would derive from the REPORT forms output blocks.

Example
/COLUMN_HEADINGS=COL_HEADINGS ! COL_HEADINGS is a PROCEDURE form that prints ! column headings via output blocks.

Forms and Form Qualifiers IAF 8.0 DML

3-47

/COLUMN_HEADING_ROW

/COLUMN_HEADING_ROW
Syntax
/COLUMN_HEADING_ROW=numeric_expression

Description
This qualifier allows you to specify the last row on which a TABLE_EDIT forms column headings (specified via the /HEADING block qualifier) are to display. If a given form header statement does not include the /COLUMN_HEADING_ROW qualifier, the last row on which column headings display is the row before the row that the /BEGIN_ROW form qualifier specifies. A form header statement that specifies the /COLUMN_HEADING_ROW qualifier must also specify the /BEGIN_ROW qualifier. For details on the /HEADING block qualifier, refer to this manuals BLOCKS AND BLOCK QUALIFIERS chapter. For details on the /BEGIN_ROW form qualifier, refer to its description in this chapter.

Example
/COLUMN_HEADING_ROW=6 /COLUMN_HEADING_ROW=#HEAD_ROW

3-48

Forms and Form Qualifiers IAF 8.0 DML

/COLUMN_SPACING

/COLUMN_SPACING
Syntax
/COLUMN_SPACING=numeric_value

Description
This qualifier allows you to specify the number of spaces IAF is to place between floating columns on a columnar REPORT form. If a given form header statement does not include the /COLUMN_SPACING qualifier, IAF places one space between floating columns.

Example
/COLUMN_SPACING=3

Forms and Form Qualifiers IAF 8.0 DML

3-49

/COMMIT_RATE

/COMMIT_RATE
Syntax
/COMMIT_RATE=numeric_expression

Description
This qualifier allows you to specify the number of records IAF is to process before it commits the current transaction. The given numeric expression must evaluate to an integer greater than zero. When the record stream is exhausted, IAF commits any records that are not an integral number of the commit rate. For example, if a given record stream retrieves seven records, and the commit rate is five, IAF processes and commits five records in one transaction and then processes and commits two records in another transaction. If a given record stream retrieves fourteen records, and the commit rate is five, IAF commits a set of five records with the first transaction, a set of five records in the second transaction, and a set of four records in the third transaction. IAF implements the /COMMIT_RATE qualifier by causing a commit transaction and a start transaction to take place, and then selecting records via a selection query. IAF stores pointers to all the records to process in virtual memory. For each pointer (commit rate of one) or set of pointers (commit rate greater than one) IAF starts a transaction, processes the pointers in the set, and then commits the transaction. For more information regarding transactions and commit rates, refer to the IAF Users Guide.

Examples
/COMMIT_RATE=10 /COMMIT_RATE=(#RATE)

3-50

Forms and Form Qualifiers IAF 8.0 DML

/DEFAULT_TAG

/DEFAULT_TAG
Syntax
/DEFAULT_TAG=tag_expression

Description
This qualifier allows you to specify the menu item that is to be the initial default item. The given tag expression should match the item tag of the menu item which is to be the initial default item. If the given tag expression matches no item tag, the initial default item is the first menu item.

Example
MENU_FORM MAIN /ROW=3 /COL=2 /HEIGHT=21 /WIDTH=78 & /TITLE=(ACME Master Menu) & /DEFAULT_TAG=FACILITY_TAG(ACME:GL) & /TAG_LENGTH=12 . . ITEM_BLOCK GENERAL_LEDGER /ROW=5 /COL=3 /FACILITY=ACME:GL . . END_FORM

Forms and Form Qualifiers IAF 8.0 DML

3-51

/DELETE_FORM

/DELETE_FORM
Syntax
/DELETE_FORM=form_name

Description
This qualifier applies to QUERY forms and TABLE_EDIT forms.

For QUERY forms:

This qualifier allows you to specify the name of a form that IAF is to execute prior to the QUERY forms standard delete form. The specified form must exist in the current compilation unit (file). The specified form can perform pre-deletion checks and/or handle the deletion of detail records that are related to a given master record selected for deletion. For example, the form that the /DELETE_FORM qualifier specifies can delete detail order lines related to an order header record selected for deletion. The exit status of the specified form can cause specific actions to occur. For example, an exit that takes place under an exit forward condition causes the QUERY form to immediately delete the given record. A normal exit causes the QUERY form to prompt the end user to confirm his or her intent to delete the record by pressing the GM_EXIT_FORWARD key. The record deletion does not take place if the specified form returns any other exit status.

For TABLE_EDIT forms:

This qualifier allows you to specify the name of a form that IAF is to execute when the end user selects a record for deletion in a TABLE_EDIT form. The specified form must exist in the current compilation unit (file). Before deleting the selected record, IAF executes the specified form. The forms can prevent deletion of the selected record from taking place by returning a failure status via the DML EXIT statement, or it can allow the deletion to continue by returning a success status via the EXIT statement. The following table illustrates these uses of the EXIT statement: EXIT Statement Format EXIT(%FAILURE) Effect Aborts the record deletion.

3-52

Forms and Form Qualifiers IAF 8.0 DML

/DELETE_FORM

EXIT Statement Format EXIT(%SUCCESS)

Effect Continues the record deletion.

For details regarding the EXIT statement, refer to this manuals LANGUAGE STATEMENTS chapter. The specified form can perform pre-deletion checks and/or handle the deletion of detail records that are related to a given master record selected for deletion. For example, the form that the /DELETE_FORM qualifier specifies can delete detail order lines related to an order header record selected for deletion.

Example
/DELETE_FORM=VERIFY_DELETION

Forms and Form Qualifiers IAF 8.0 DML

3-53

/END_ROW

/END_ROW
Syntax
/END_ROW=numeric_expression

Description
This qualifier applies to REPORT forms and TABLE_EDIT forms.

For REPORT forms:

This qualifier allows you to specify the last row on which a detail line is to print on a report page. If a given REPORT_FORM statement does not include this qualifier, the last print row is 10 rows less than the form height, which is 66 lines for a standard form. Therefore, if the REPORT_FORM statement does not include this qualifier, the last detail print row is row 56.

For TABLE_EDIT forms:

This qualifier allows you to specify the last row on which a record is to display in a TABLE_EDIT forms window. If a given TABLE_FORM statement does not include this qualifier, the last display row is the windows last row. This qualifier, in conjunction with the /BEGIN_ROW qualifier, allows you to place any TEXT declarations after the last displayed record in the TABLE_EDIT forms window. For details on the /BEGIN_ROW qualifier, refer to its description in this chapter. For details on TEXT declarations, refer to this manuals FIXED DISPLAY DECLARATIONS chapter.

Example
/END_ROW=#LAST_LINE

3-54

Forms and Form Qualifiers IAF 8.0 DML

/FIND_FORM

/FIND_FORM
Syntax
/FIND_FORM=form_name

Description
This qualifier applies to QUERY, REPORT, and TABLE_EDIT forms.

For QUERY forms:

This qualifier allows you to specify the name of a form that IAF is to execute in place of a QUERY forms standard find form. The specified form must exist in the current compilation unit (file). For a query given via the alternate form to execute, the alternate form must exit under an explicit exit forward condition. This occurs if the end user presses the GM_EXIT_FORWARD key, or an EXIT(%EXIT_FORWARD) statement executes. For details on the EXIT statement, refer to this manuals LANGUAGE STATEMENTS chapter. If the end user presses the GM_SELECT_MODE key in FIND mode, the current field in the find form becomes a multiple input window. A multiple input window facilitates entering a range of data and/or multiple data values as the selection criteria upon which the QUERY forms record selection process is to operate.

For REPORT forms:

This qualifier allows you to specify the name of an alternate form that IAF is to execute before the REPORT form whose REPORT_FORM statement includes this qualifier. The specified form must exist in the current compilation unit and should enable end users to enter record selection criteria for the fields that reside in the table(s) that the REPORT_FORM statements /TABLE qualifier specifies. The resulting record set reflects the record selection criteria given in response to the find form, as well as any selection criteria that the REPORT_FORM statement specifies. For details on the /TABLE qualifier, refer to its description in this chapter.

Forms and Form Qualifiers IAF 8.0 DML

3-55

/FIND_FORM

For TABLE_EDIT forms:

This qualifier allows you to specify the name of a form that IAF is to execute when the end user presses the GM_FIND_ROW key prior to or during the time that a TABLE_EDIT form displays records. The specified form must exist in the current compilation unit and should enable end users to enter record selection criteria for the fields that reside in the table(s) that the TABLE_FORM statements /TABLE qualifier specifies. The resulting display reflects the record selection criteria given in response to the find form, as well as any selection criteria that the TABLE_FORM statement specifies. Note that you can use the /OPTIONS=START_FIND qualifier to force a TABLE_EDIT form to execute the find form before displaying any records. For details on the /TABLE and /OPTIONS qualifiers, refer to their descriptions in this chapter. If the end user presses the GM_SELECT_MODE key in FIND mode, the current field in the find form becomes a multiple input window. A multiple input window facilitates entering a range of data and/or multiple data values as the selection criteria upon which the TABLE_EDIT forms record selection process is to operate. IAF displays an error message if an end user presses GM_FIND_ROW in a TABLE_EDIT forms window whose TABLE_FORM statement does not include the /FIND_FORM qualifier.

Example
/FIND_FORM=SALES_ORDER_SEARCH

3-56

Forms and Form Qualifiers IAF 8.0 DML

/FIRST

/FIRST
Syntax
/FIRST=numeric_expression

Description
This qualifier applies to all form types except MENU forms, and allows you to specify the maximum number of records that a given form can select. IAF generates an implicit /FIRST qualifier for TABLE_EDIT and QUERY forms if the GEM_SELECT_LIMIT SCV is defined. However, appending an explicit /FIRST qualifier to a TABLE_FORM or QUERY_FORM statement overrides any value that GEM_SELECT_LIMIT specifies. For details on GEM_SELECT_LIMIT, refer to the IAF guide that applies to your operating system.

Example
/FIRST=(#MAXIMUM_RECS * 1.5)

Forms and Form Qualifiers IAF 8.0 DML

3-57

/FOOTING

/FOOTING
Syntax
/FOOTING=expression

Description
This qualifier allows you to specify a page footing that is to print at the bottom center of each page of a given report. A REPORT_FORM statement can include any number of /FOOTING qualifiers, as well as /LFOOTING and /RFOOTING qualifiers. IAF determines the complete page footings for a report by examining the /FOOTING, /LFOOTING, and /RFOOTING qualifier expressions in the order in which the REPORT_FORM statement includes them. IAF places the footings left to right across the bottom of the report page, unless a given footings justification requires it to print on a new line. For details regarding the /LFOOTING and /RFOOTING qualifiers, refer to their descriptions in this chapter.

Example
REPORT_FORM MAIN /TABLE=SALES_ORDERS & /FOOTING=My Company Name & /LFOOTING=Sales Orders Report & /RFOOTING=(Page & %PAGE) & /FOOTING=Northwest Division

The page footings that this example generates appears as follows:

Figure 3-1: Report Page Footings

3-58

Forms and Form Qualifiers IAF 8.0 DML

/FOOTING_FORM

/FOOTING_FORM
Syntax
/FOOTING_FORM=form_name

Description
This qualifier allows you to specify the name of a form that contains the page footings a REPORT form is to use. The footings in the form that the /FOOTING_FORM qualifier specifies override footings that any /FOOTING, /LFOOTING, or /RFOOTING qualifiers specify. For details on the /FOOTING, /LFOOTING, and /RFOOTING qualifiers, refer to their descriptions in this chapter. Footing forms reserve space at the end of each report page. However, it is possible to override this behavior and force the positioning of footing text as the first example on the following page illustrates.

Examples
/FOOTING_FORM=SPECIAL_FOOTINGS . . PROCEDURE_FORM SPECIAL_FOOTINGS OUTPUT_BLOCK START /ROW=1 /COL=1 /SOURCE= OUTPUT_BLOCK DEPARTMENT /ROW=60 /COL=30 /SOURCE=(#Department) ! This block displays the department name. OUTPUT_BLOCK DATE /ROW=61 /COL=1 /SOURCE=(%NOW) ! This block displays the current date/time at run-time. OUTPUT_BLOCK END /ROW=62 /COL=1 /SOURCE= END_FORM

Forms and Form Qualifiers IAF 8.0 DML

3-59

/FOOTING_FORM

Assuming that the current report page length is 62 rows, this example uses dummy blocks (START and END) to define the beginning and end of the footing form to match the beginning and end of the report page. This eliminates the reserved space (4 rows) that normally follows a footing form, and allows the placement of the output blocks, DEPARTMENT and DATE, as desired.
/FOOTING_FORM=SPECIAL_FOOTINGS . . PROCEDURE_FORM SPECIAL_FOOTINGS OUTPUT_BLOCK DEPARTMENT /ROW=10 /COL=30 /SOURCE=(#Department) OUTPUT_BLOCK DATE /ROW=20 /COL=1 /SOURCE=(%NOW) END_FORM

This example produces a footing form having 11 rows. The DEPARTMENT output block displays to the first row of the footing form, while the DATE output block displays to the last row of the footing form.

3-60

Forms and Form Qualifiers IAF 8.0 DML

/GROUPED_BY

/GROUPED_BY
Syntax
/GROUPED_BY=[context.]field_name[,...] or /GROUPED_BY=field_name[sub_grouped_by_clause][,...] or /GROUPED_BY=(#variable_name[,#variable_name[,...]])

Description
This qualifier applies to NORMAL, REPORT, and PROCEDURE forms. It allows you to reduce the data to a set of representative records, each of which contains a unique value for the specified field. Each record represents one or more records having a particular value for the field. IAF determines the record that is to represent each group. The GROUPED_BY qualifier also determines the default sort criteria for a given record stream. You can override this default sort criteria by appending an explicit /SORTED_BY qualifier to the given form header statement. For details regarding the /SORTED_BY qualifier, refer to its description in this chapter. Unlike the /REDUCED_TO qualifier, the GROUPED_BY qualifier maintains access to all selected records (not just the representative records). Therefore, you can use this qualifier with the /STATISTICS qualifier to retrieve summarized information from all selected records. For details regarding the /REDUCED_TO and /STATISTICS qualifiers, refer to their descriptions in this chapter. A form header statement may include multiple /GROUPED_BY qualifiers. Specifying multiple /GROUPED_BY qualifiers is equivalent to specifying one /GROUPED_BY qualifier with multiple grouped by clauses.

Forms and Form Qualifiers IAF 8.0 DML

3-61

/GROUPED_BY

Sub-group Clauses
The /GROUPED_BY qualifier facilitates specifying a sub-group clause defining a larger bucket (granularity) for numeric and date/time fields. By default, date/time fields in IAF are accurate to one hundredth of a second on database engines that support that level of accuracy. Therefore, grouping by a date/time field can result in as many groups as there are records. Specifying a sub-group clause facilitates grouping by time spans greater than the default, thereby producing fewer groups, with each group holding more records. Following is the format to use for a sub-group clause:
BY [nnn] keyword [CONTINUOUS]

The following table lists and describes the components of a sub-group clause. Component BY Description This operator begins the sub-group clause and appends the remaining components of the clause to the specified field. This is an optional value that indicates a multiple of the given bucket (e.g. 6 MONTHS). If this value is not present, the bucket is singular. This is a keyword (SECONDS, MINUTES, HOURS, DAYS, WEEKS, MONTHS, YEARS, or NUMBERS) indicating the bucket or granularity to use when grouping records. The keywords apply only to date/time fields, except the NUMBERS keyword which applies to any numeric field. This keyword causes IAF to return a continuous range of values including any missing values for the given bucket. IAF supplies missing values between the lowest and highest actual values. For example, a bar graph that groups sales by month shows a bar for each month even if no sales occurred during some months (those months have a bar height of zero.)

[nnn]

keyword

[CONTINUOUS]

3-62

Forms and Form Qualifiers IAF 8.0 DML

/GROUPED_BY

The following table lists the starting point for each bucket type. Bucket Type SECONDS Starting Point %%-%%%-%%%% %%:%%:00 Description When hundredths of seconds (if supported) roll over to 00, a new bucket begins. When seconds roll over to 00, a new bucket begins. When minutes roll over to 00, a new bucket begins. When hours roll over to 24, a new bucket begins. The first bucket begins on the first Sunday in the given year. Subsequent buckets begin on subsequent Sundays. The first bucket begins on January 1 of the given year. Subsequent buckets begin on the first day of subsequent months. The first bucket begins on January 1, 1800. Subsequent buckets begin on January 1 of subsequent years. The first bucket begins at 0. Subsequent buckets begin at the given interval (1 by default).

MINUTES

%%-%%%-%%%% %%:00:00 %%-%%%-%%%% 00:00:00

HOURS

DAYS

01-%%%-%%%% 00:00:00

WEEKS

first Sunday in the year

MONTHS

01-JAN-%%%% 00:00:00

YEARS

01-JAN-1800 00:00:00

NUMBERS

Forms and Form Qualifiers IAF 8.0 DML

3-63

/GROUPED_BY

To illustrate how buckets work, assume that the given form header statement includes the following /GROUPED_BY qualifier:
/GROUPED_BY=TRANSACTION_DATE BY 7 HOURS

and the first transaction occurred on 12-Sep-1998 at 14:02:03. The following table illustrates the effect of the given /GROUPED_BY qualifier. Bucket Bucket #1 Bucket #2 Bucket #3 Starting Point 12-Sep-1998 00:00:00:00 12-Sep-1998 07:00:00:00 12-Sep-1998 14:00:00:00 Notes This bucket is empty. This bucket is empty. This bucket holds the first transaction and may hold others, depending upon subsequent records. Subsequent records determine the contents of this bucket. Subsequent records determine the contents of this bucket. Subsequent records determine the contents of this bucket The last transaction date determines the last bucket.

Bucket #4 Bucket # 5 Bucket #6 ...

12-Sep-1998 21:00:00:00 13-Sep-1998 04:00:00:00 13-Sep-1998 11:00:00:00 ...

Examples
/GROUPED_BY=DEPARTMENT

This qualifier causes IAF to select one record for each department, but to return information for all records within each department.
/GROUPED_BY=(DEPARTMENT,ORDER_DATE)

This qualifier causes IAF to select one record for each department/order date combination, but to return information for all records in each group.
/GROUPED_BY=TRANSACTION_DATE BY MONTHS CONTINUOUS

This qualifier causes IAF to select one record for each month in which a transaction took place and to supply dummy values for any months in which no transaction took place, but to return information for all records representing transactions that took place in each month.
3-64 Forms and Form Qualifiers IAF 8.0 DML

/GROUPED_BY

/GROUPED_BY=TRANSACTION_DATE BY 2 MONTHS

This qualifier causes IAF to select one record for each two month period in which a transaction took place, but to return information for all records representing transactions that took place in each two month period.
/GROUPED_BY=YEAR,PERIOD_NUMBER BY 3 NUMBERS

This qualifier causes IAF to select one record for every three periods in each year, but to return information for all records pertaining to each group of three periods. For example, if there are 12 periods in a year, this selects four records at the very most.

Forms and Form Qualifiers IAF 8.0 DML

3-65

/HEADING

/HEADING
Syntax
/HEADING=expression

Description
This qualifier allows you to specify a heading that is to print at the top center of each page of a given report. A REPORT_FORM statement can include any number of /HEADING qualifiers, as well as /LHEADING and /RHEADING qualifiers. IAF determines the complete page headings for a report by examining the /HEADING, /LHEADING, and /RHEADING qualifier expressions in the order in which the REPORT_FORM statement includes them. IAF places headings left to right across the top of the page, unless a given headings justification requires it to print on a new line. For details regarding the /LHEADING and /RHEADING qualifiers, refer to their descriptions in this chapter.

iBrowser Note
For iBrowser, /HEADING truncates the text to the width of the column as a maximum limit for the heading.

Example
REPORT_FORM MAIN /TABLE=SALES_ORDERS & /LHEADING=%TODAY & /RHEADING=(Page & %PAGE) & /HEADING=Orders Report & /LHEADING=(Department: & ORDERS(DEPARTMENT))

The page headings that this example generates appear as follows:

6-DEC-1998 14:33:32:51 Orders Report Department: 01 Page 1

Figure 3-2: Report Page Headings

3-66

Forms and Form Qualifiers IAF 8.0 DML

/HEADING_FORM

/HEADING_FORM
Syntax
/HEADING_FORM=form_name

Description
This qualifier allows you to specify the name of a form that IAF is to execute to produce the page headings for a given REPORT form. The headings that the heading form specifies override those that any /HEADING, /LHEADING, or /RHEADING qualifiers specify.

Example
/HEADING_FORM=PAGE_HEADINGS ! PAGE_HEADINGS is a PROCEDURE form ! that uses output blocks to print the page headings.

Forms and Form Qualifiers IAF 8.0 DML

3-67

/HEIGHT

/HEIGHT
Syntax
/HEIGHT=numeric_expression

Description
This qualifier allows you to specify the number of display rows a forms window is to have or lines a report page is to have. It is applicable to all form types except PROCEDURE forms, and is mandatory for NORMAL, TABLE_EDIT, QUERY, and MENU forms.

Examples
/HEIGHT=19 /HEIGHT=(#MAX_HEIGHT/2)

3-68

Forms and Form Qualifiers IAF 8.0 DML

/INPUT_ROW_HEIGHT

/INPUT_ROW_HEIGHT
Syntax
/INPUT_ROW_HEIGHT=numeric_expression

Description
This qualifier allows you to specify the number of rows to use for the input area that is active when an end user presses the GM_INSERT_ROW or GM_SELECT_ROW key in a TABLE_EDIT form to insert a new record or select a record for modification, respectively. By default, the input area accommodates the number of rows that the TABLE_EDIT forms blocks require.

Example
/INPUT_ROW_HEIGHT=4

Forms and Form Qualifiers IAF 8.0 DML

3-69

/JOINED_TO

/JOINED_TO
Syntax
/JOINED_TO=table_name

Description
This qualifier causes IAF to select only records that it can join to the specified tables current record. IAF looks for a join key in the first table that the given form header statements /TABLE qualifier specifies. This qualifier is especially useful when processing master records and related detail records. It specifies the master table, and the /TABLE qualifier specifies the detail table(s). This qualifier makes join key derivation a run-time decision, and eliminates the need to use hard coded join keys. If possible, use it instead of an explicit /WITH clause to join tables.

Example
PROCEDURE_FORM MAIN /TABLE=ORDER_LINES /JOINED_TO=ORDERS ! Process all ORDER_LINES records that are related to the ! current ORDERS record.

3-70

Forms and Form Qualifiers IAF 8.0 DML

/LFOOTING

/LFOOTING
Syntax
/LFOOTING=expression

Description
This qualifier allows you to specify a page footing that is to print at the bottom left of each page of a given report. A REPORT_FORM statement can include any number of /LFOOTING qualifiers, as well as /FOOTING and /RFOOTING qualifiers. IAF determines the complete page footings for a report by examining the /LFOOTING, /FOOTING, and /RFOOTING qualifier expressions in the order in which the REPORT_FORM statement includes them. IAF places the footings left to right across the bottom of the report page, unless a given footings justification requires it to print on a new line. For details regarding the /FOOTING and /RFOOTING qualifiers, refer to their descriptions in this chapter.

Example
REPORT_FORM MAIN /TABLE=SALES_ORDERS & /FOOTING=My Company Name & /LFOOTING=Sales Orders Report & /RFOOTING=(Page & %PAGE) & /LFOOTING=Northwest Division

The page footings that this example generates appear as follows:

Figure 3-3: Report Page Footings

Forms and Form Qualifiers IAF 8.0 DML

3-71

/LHEADING

/LHEADING
Syntax
/LHEADING=expression

Description
This qualifier allows you to specify a heading that is to print at the top left of each page of a given report. A REPORT_FORM statement can include any number of /LHEADING qualifiers, as well as /HEADING and /RHEADING qualifiers. IAF determines the complete page headings for a report by examining the /LHEADING, /HEADING, and /RHEADING qualifier expressions in the order in which the REPORT_FORM statement includes them. IAF places headings left to right across the top of the page, unless a given headings justification requires it to print on a new line. For details regarding the /HEADING and /RHEADING qualifiers, refer to their descriptions in this chapter.

iBrowser Note
/LHEADING will display the complete heading text aligned to the left. If it exceeds the limit of the table, it will truncate. In case there is not enough space for the text, it will omit the heading.

Example
REPORT_FORM MAIN /TABLE=SALES_ORDERS & /LHEADING=%TODAY & /RHEADING=(Page & %PAGE) & /LHEADING=Orders Report &

The page headings that this example generates appear as follows:

6-DEC-1998 Orders Report ID Figure 3-4: ReportM i Headings Page Titl Page 1

P i

t d R

3-72

Forms and Form Qualifiers IAF 8.0 DML

/LINES_AFTER

/LINES_AFTER
Syntax
/LINES_AFTER=numeric_expression or /LINES_AFTER=TOP_OF_PAGE

Description
This qualifier allows you to specify the number of blank lines that are to print after each detail line on a REPORT form. If a REPORT_FORM statement does not include the /LINES_AFTER qualifier, IAF does not print any blank lines after each detail line. Using the TOP_OF_PAGE keyword instead of a numeric expression causes a new report page to begin after each detail line prints.

Examples
/LINES_AFTER=2 /LINES_AFTER=#AFTER_DETAIL

Forms and Form Qualifiers IAF 8.0 DML

3-73

/LINES_BEFORE

/LINES_BEFORE
Syntax
/LINES_BEFORE=numeric_expression or /LINES_BEFORE=TOP_OF_PAGE

Description
This qualifier allows you to specify the number of blank lines that are to print before each detail line on a REPORT form. If a REPORT_FORM statement does not include the /LINES_BEFORE qualifier, IAF does not print any blank lines before each detail line. Using the TOP_OF_PAGE keyword in place of a numeric expression causes a new report page to begin before each detail line prints.

Examples
/LINES_BEFORE=2 /LINES_BEFORE=#BEFORE_DETAIL

3-74

Forms and Form Qualifiers IAF 8.0 DML

/LOCK

/LOCK
Syntax
/LOCK=keyword

Description
This qualifier allows you to specify the type of data stream lock that IAF is to place on the records that a given stream fetches. This qualifier is applicable to all form types except MENU forms (it also applies to DML statements that start streams, such as the FIND and START_STREAM statements). If a given form header statement does not include the /LOCK qualifier, the database engine determines the default locking mechanism to apply to the records. For information regarding the default locking mechanism for a particular database engine, refer to the IAF guide that applies to that database engine. The following table lists and describes the keywords that are valid for use with the /LOCK qualifier. Keyword NONE Description This keyword indicates that IAF is to place no locks on records that the record stream selects. This lock mode operates within the context of read-only and read/write transactions that are simultaneous. It allows other users to update records that the stream retrieves because it retrieves the data via the read-only transaction. This means that data that the stream retrieves might not be current because other processes that access the data after the record stream starts can add, modify, or delete records without any visible change to the read-only transaction. Therefore, to maintain referential and data integrity, do not use data to update records in the database if the data was retrieved via a record stream using /LOCK=NONE mode. You may write to a record retrieved via a record stream using /LOCK=NONE mode as long as another user has not updated the record since the stream began. Otherwise, attempting to write to the record causes the transaction to roll back, and the update to fail.

Forms and Form Qualifiers IAF 8.0 DML

3-75

/LOCK

Keyword READ

Description This keyword indicates that IAF is to place an immediate READ lock on records that the record stream retrieves. Normally, the database engine promotes a users READ lock to a WRITE lock only if the user attempts to write to a record in the stream. This keyword indicates that IAF is to place an immediate WRITE lock on records that the record stream retrieves. By default, records receive READ locks. WRITE lock mode prevents the type of deadlock situation that occurs when two users having READ locks attempt to write to the same record. WRITE lock mode is especially useful for applications that update each record that the record stream retrieves. Note that because IAF does not allow updates on multiple table views, it does not place WRITE locks on them.

WRITE

For more information regarding streams, data locks, and deadlock situations, refer to the IAF Users Guide.

Examples
PROCEDURE_FORM AA /TABLE=ORDERS & /WITH=ORDERS(DATE)=#DAY_DATE & /LOCK=WRITE ! This places a WRITE lock on the selected records. TABLE_FORM MAIN /TABLE=CUSTOMERS & /WITH=NAME CONTAINING SMITH & /LOCK=NONE ! This displays all customers named Smith, but places no ! locks on the selected record.

3-76

Forms and Form Qualifiers IAF 8.0 DML

/MODIFY_FORM

/MODIFY_FORM
Syntax
/MODIFY_FORM=form_name

Description
This qualifier allows you to specify the name of an alternate form to execute in place of the standard modification form when an end user enters MODIFY mode via the GM_SELECT_ROW key to modify a record in a QUERY form. The specified form must exist in the current compilation unit. For the given modification to take place, the alternate form must exit under an explicit exit forward condition. This condition occurs if the end user exits the form via the GM_EXIT_FORWARD key, or a DML EXIT(%EXIT_FORWARD) statement executes. For details regarding the EXIT statement, refer to this manuals LANGUAGE STATEMENTS chapter.

Examples
/MODIFY_FORM=EDIT_PART

Forms and Form Qualifiers IAF 8.0 DML

3-77

/NOERROR

/NOERROR
Syntax
/NOERROR

Description
This qualifier disables the error message that normally displays if a TABLE_FORM statement including the /OPTIONS=MENU or /READ_ONLY qualifier specifies record selection criteria for which there are no matching records. By default, if no matching records exist, IAF displays an error message as the TABLE_EDIT form exits. Appending this qualifier to a given TABLE_FORM statement allows the DML routine that performs the form to handle errors that occur within it instead of having IAF handle them. After the TABLE_EDIT form exits, the DML routine can check the %STATUS special variable to determine whether or not an error occurred within the form. For details regarding %STATUS, refer to the SPECIAL VARIABLES AND VALUE SYMBOLS chapter.

Example
FORM A ... . . PERFORM B IF (%STATUS <> %NORMAL) ERROR (My personal error message) END_IF . . END_FORM TABLE_FORM B /NOERROR ... . . END_FORM

3-78

Forms and Form Qualifiers IAF 8.0 DML

/NOEXIT_FORWARD

/NOEXIT_FORWARD
Syntax
/NOEXIT_FORWARD

Description
This qualifier prevents end users from being able to exit the given form by pressing the GM_EXIT_FORWARD key at an input, and is applicable to any form that contains input blocks. The /NOEXIT_FORWARD qualifier is especially useful in forms containing input blocks that require the end user to enter explicit data. Specifying the /EXIT_FORWARD block qualifier for an input block overrides this behavior. For details regarding the /EXIT_FORWARD qualifier, refer to this manuals Blocks And Block Qualifiers chapter.

Forms and Form Qualifiers IAF 8.0 DML

3-79

/NOSTATUS

/NOSTATUS
Syntax
/NOSTATUS

Description
This qualifier indicates that IAF is not to display the status window associated with a given REPORT form. By default, IAF displays a status window if the processing phase of a REPORT form exceeds twenty seconds. The processing phase includes any operations that IAF performs on the selected records based upon the qualifiers that the given REPORT_FORM statement specifies (sorting, grouping, and so on.) Note that the status window does not display during a REPORT forms record selection phase, regardless of its duration.

3-80

Forms and Form Qualifiers IAF 8.0 DML

/OPTIONS

/OPTIONS
Syntax
/OPTIONS=option[,option[,...]]

Description
This qualifier applies to QUERY, REPORT, and TABLE_EDIT forms.

For QUERY forms:

This qualifier allows you to specify query option keywords to change the default behavior of a QUERY form. You may specify the query options in any logical combination. The table on the following page lists and describes the option keywords that are valid for use with the /OPTIONS qualifier that a QUERY_FORM statement includes. Query Option Keywords Keyword AUDIT EXECUTE Description Makes TED and QBF perform data auditing on all table fields by default. This option causes IAF to produce a record set based upon the given table and selection qualifiers, and sets the QUERY forms initial mode to DISPLAY mode. This option causes the QUERY form to exit FIND mode if IAF produces an empty record set. By default, the QUERY form re-enters FIND mode if the record set is empty. Typically, this option is used in conjunction with the EXECUTE option. This query option disallows DELETE mode in the QUERY form. This query option disallows FIND mode in the QUERY form. This query option disallows INSERT mode in the QUERY form.

EXIT_EMPTY

NODELETE NOFIND NOINSERT

Forms and Form Qualifiers IAF 8.0 DML

3-81

/OPTIONS

Query Option Keywords Keyword NOMODIFY START_INSERT Description This query option disallows MODIFY mode in the QUERY form. This query option changes the QUERY forms initial mode to INSERT instead of FIND.

For REPORT forms:

This qualifier allows you to specify report option keywords to define the general layout of a printed report. Detailed descriptions of the report option keywords follow, including examples of their use, in alphabetical order by keyword.
COMPLETE

NOTE:
This report option is mutually exclusive with the CONTINUE, MERGED, and OVERLAID options, and is the default if the given REPORT form does not explicitly specify the CONTINUE, MERGED, or OVERLAID option. If the REPORT form that specifies this option is the main report (i.e. no other REPORT form calls it), this option causes IAF to close the report output file upon completing execution of the REPORT form. If the REPORT form that specifies this option is a sub-report (i.e. another REPORT form calls it), and it uses the same output file as the main report (i.e. the calling REPORT form), this option causes a form feed to precede and follow any sub-report printing. If the REPORT form that specifies this option is a sub-report (i.e. another REPORT form calls it), and it uses an output file other than the one that the calling REPORT form uses, this option causes IAF to do any subreport printing to the called REPORT forms output file and not to the calling REPORT forms output file. However, because the called REPORT form can specify only one output file, each time a sub- report prints to the file it either overwrites the files previous contents or prints to a new version of the file, depending upon the given operating system.

3-82

Forms and Form Qualifiers IAF 8.0 DML

/OPTIONS

The following shows the general syntactical format of a calling REPORT form (i.e. a main report) and the REPORT form it calls (a sub-report), which specifies the COMPLETE option.
REPORT_FORM A & /TABLE=A & /SORTED_BY=(NAME) & /WITH=CUST_ID <> 000000 . . OUTPUT_BLOCK ... . . BEGIN_BLOCK SUB_REPORT PERFORM B ! Instead of executing REPORT form B via a PERFORM ! statement, REPORT form A could use a /BREAK ! qualifier to execute it. END_BLOCK END_FORM REPORT_FORM B & /TABLE=B & /JOINED_TO=A & /SORTED_BY=(DATE) & /WITH=(DATE > 31-DEC-1998) & /OPTIONS=COMPLETE . . OUTPUT_BLOCK ... . . END_FORM

Following is an executable example that uses this general syntactical format, followed by example pages of the output report file it produces.
TITLE MOVIES,MOVIES REPORT REPORT_FORM MAIN & /READ_ONLY & /WIDTH=80 & /OUTPUT=(MOVIES_REPORT) & /TABLE=MOVIES & /LHEADING=(%NOW) & /RHEADING=(MASK(Page !-@@@@@, %PAGE)) & /HEADING=(MOVIES INVENTORY REPORT) OUTPUT_BLOCK MOVIE_ID /SOURCE=(MOVIES(MOVIE_ID)) OUTPUT_BLOCK MOVIE_TITLE /SOURCE=(MOVIES(MOVIE_TITLE)) OUTPUT_BLOCK PRICE /SOURCE=(MOVIES(PRICE)) OUTPUT_BLOCK TIMES_RENTED /SOURCE=(MOVIES(TIMES_RENTED)) BEGIN_BLOCK DO_SUB_REPORT PERFORM RENTAL_REPORT END_BLOCK END_FORM

Forms and Form Qualifiers IAF 8.0 DML

3-83

/OPTIONS

REPORT_FORM RENTAL_REPORT & /READ_ONLY & /WIDTH=80 /COLUMN_SPACING=6 & /OPTIONS=COMPLETE & /OUTPUT=(MOVIES_REPORT) & /TABLE=RENTALS & /JOINED_TO=MOVIES & /LHEADING=(%NOW) & /RHEADING=(MASK(Page !-@@@@@, %PAGE)) & /HEADING=(MOVIE RENTAL REPORT: & MOVIES(MOVIE_TITLE)) OUTPUT_BLOCK MEMBER_ID /SOURCE=(RENTALS(MEMBER_ID)) OUTPUT_BLOCK DATE_RENTED /SOURCE=(RENTALS(DATE_RENTED))
OUTPUT_BLOCK DATE_RETURNED /SOURCE=(RENTALS(DATE_RETURNED))

OUTPUT_BLOCK DAYS /SOURCE=(RENTALS(DAYS)) END_FORM

6-DEC-1998 14:32:32:51 Page 1 MOVIES INVENTORY REPORT Movie Times Movie Title Price Rented ID ADV619 Indiana Jones $1.99 2 6-DEC-1998 14:33:32:51 Page 1 MOVIES RENTAL REPORT: Indiana Jones Date Date Rented Returned Days R Member BAB4406637 17-NOV-1998 18-NOV-1998 1 GL_2187038 15-NOV-1998 16-NOV-1998 1 Figure 3-5: COMPLETE Report Option Example

In this example, the main report prints information regarding each movie in the current inventory. For any movie that has been rented, the subreport prints to the same output file a list of the rental transactions that have taken place for the movie. A form feed precedes and follows printing of the sub-report information.
CONTINUE

NOTE:
This report option is mutually exclusive with the COMPLETE, MERGED, and OVERLAID options. The CONTINUE option is intended for use with a REPORT form that is a sub-report (i.e. a REPORT form that another REPORT form calls) that specifies an output file other than the one that the main report (i.e. the calling REPORT form) specifies. The CONTINUE option makes available to the sub-report the data that the main report processes.

3-84

Forms and Form Qualifiers IAF 8.0 DML

/OPTIONS

The following page shows the general syntactical format of a calling REPORT form (i.e. a main report) and the REPORT form it calls (i.e. a sub-report), which specifies the CONTINUE option.
REPORT_FORM A & /TABLE=A & /SORTED_BY=(NAME) & /OUTPUT=A.LIS . . OUTPUT_BLOCK ... . . BEGIN_BLOCK SUB_REPORT PERFORM B ! Instead of executing REPORT form B via a PERFORM ! statement, REPORT form A could use a /BREAK ! qualifier to execute it. END_BLOCK END_FORM REPORT_FORM B & /OUTPUT=B.LIS & /OPTIONS=CONTINUE . . OUTPUT_BLOCK ... . . END_FORM

Following is an executable example that uses this general syntactical format with a /BREAK qualifier as noted in the comment above, followed by example pages of the output report files it produces.
TITLE MOVIES,MOVIES REPORT REPORT_FORM MAIN & /READ_ONLY & /WIDTH=80 & /OUTPUT=(MOVIES_REPORT) & /TABLE=MOVIES & /SORTED_BY=MOVIES(MOVIE_TYPE) & /BREAK=CLEAR_TOTALS, TYPE_REPORT, MOVIES(MOVIE_TYPE) & /LHEADING=(%NOW) & /RHEADING=(MASK(Page !-@@@@@, %PAGE)) & /HEADING=(MOVIES INVENTORY REPORT) OUTPUT_BLOCK MOVIE_ID /SOURCE=(MOVIES(MOVIE_ID)) OUTPUT_BLOCK MOVIE_TITLE /SOURCE=(MOVIES(MOVIE_TITLE)) OUTPUT_BLOCK PRICE /SOURCE=(MOVIES(PRICE)) OUTPUT_BLOCK TIMES_RENTED /SOURCE=(MOVIES(TIMES_RENTED)) OUTPUT_BLOCK MOVIE_TYPE /SOURCE=(MOVIES(MOVIE_TYPE))

Forms and Form Qualifiers IAF 8.0 DML

3-85

/OPTIONS

BEGIN_BLOCK CALCULATE_TOTALS #TIMES_RENTED=#TIMES_RENTED + MOVIES(TIMES_RENTED) #TOTAL_REVENUE=#TOTAL_REVENUE + & (MOVIES(TIMES_RENTED) * MOVIES(PRICE)) END_BLOCK END_FORM PROCEDURE_FORM CLEAR_TOTALS #TIMES_RENTED=0 #TOTAL_REVENUE=0 END_FORM REPORT_FORM TYPE_REPORT & /READ_ONLY & /WIDTH=80 & /OPTIONS=CONTINUE & /OUTPUT=(TYPE_REPORT) & /TABLE=MOVIE_TYPES & /JOINED_TO=MOVIES & /LHEADING=(%NOW) & /RHEADING=(MASK(Page !-@@@@@, %PAGE)) & /HEADING=(MOVIE TYPE SUMMARY REPORT) OUTPUT_BLOCK MOVIE_TYPE /SOURCE=(MOVIES(MOVIE_TYPE))
OUTPUT_BLOCK DESCRIPTION /SOURCE=(MOVIE_TYPES(DESCRIPTION))

OUTPUT_BLOCK TIMES_RENTED /SOURCE=#TIMES_RENTED & /HEADING=Times,Rented OUTPUT_BLOCK TOTAL_REVENUE /SOURCE=#TOTAL_REVENUE & /USING=MOVIES(PRICE) /HEADING=Total,Revenue END_FORM

6-DEC-1998 14:33:32:51 Page 1 MOVIES INVENTORY REPORT Movie Times M Movie Title Price Rented R ID ADV296 Indiana Jones $1.50 2 A ADV480 Diamonds Are Forever $2.00 46 A ADV721 Die Hard $1.00 7 A COM229 Men in Black $2.25 60 C ROM010 Little Women $1.00 10 R SFI394 Spaceship of Zombies $2.00 69 S 6-DEC-1998 14:33:33:12 MOVIE TYPE SUMMARY REPORT M T A C R S Times Description Rented Adventure 55 Comedy 60 Romance 10 Science Fiction 69 Page 1

Total Revenue $102.00 $135.00 $ 10.00 $138.00

Figure 3-6: CONTINUE Report Option Example

3-86

Forms and Form Qualifiers IAF 8.0 DML

/OPTIONS

In this example, the main report prints information regarding each movie in the current inventory sorted by movie type (A for Adventure, C for Comedy, etc.). Each time a break occurs on movie type (the current movie type changes), the sub-report prints to a separate output file summary information regarding the movie type that was current before the break.

INFINITE
This report option causes IAF to treat the given report as a single page by printing page and column headings only on the reports first page and printing page footings only on the reports last page. IAF prints the reports records continuously, using as many pages as necessary. This option does not change the number of lines that print per page (i.e. the default of 66, or the number that the /HEIGHT form qualifier specifies). This option causes IAF to disable any REPOSITION statements in the REPORT form, thereby preventing any detail record from printing on any line that precedes the forms current line. For details regarding the REPOSITION statement, refer to this manuals LANGUAGE STATEMENTS chapter.

Forms and Form Qualifiers IAF 8.0 DML

3-87

/OPTIONS

Following is an executable example that uses the INFINITE option, followed by example pages of the output report file it produces.
TITLE MOVIES,MEMBERS REPORT REPORT_FORM MAIN & /READ_ONLY & /WIDTH=80 & /OPTIONS=INFINITE & /OUTPUT=(MEMBERS_REPORT) & /TABLE=MEMBERS & /LHEADING=(%NOW) & /RHEADING=(MASK(Page !-@@@@@, %PAGE)) & /HEADING=(Members Report) & /FOOTING=(Video Plus) OUTPUT_BLOCK MEMBER_ID /SOURCE=(MEMBERS(MEMBER_ID)) OUTPUT_BLOCK LAST_NAME /SOURCE=(MEMBERS(LAST_NAME)) OUTPUT_BLOCK FIRST_NAME /SOURCE=(MEMBERS(FIRST_NAME)) OUTPUT_BLOCK CITY /SOURCE=(MEMBERS(CITY)) END_FORM

6-DEC-1998 14:33:32:51 MEMBERS REPORT Member Last Name ID AJR908016 Anderson ALA890435 Ames ALQ890319 Anriola BAB891227 Boyd BDG890305 Barlett UDF891220 WB_890603 WCD890771 WC_891129 ZAF891027 Vormelker Wood Watters Watters Ziemke Video Plus

Page 1 First Name John R. Louie A. Leslie Q. Ann B. Dean G. Norman P. Brian Katie P. Melinda Al F.

City Escondido Escondido San Marcos San Diego Escondido El Cajon Escondido San Marcos Escondido San Marcos

Figure 3-7: INFINITE Report Option Example

3-88

Forms and Form Qualifiers IAF 8.0 DML

/OPTIONS

MERGED NOTE:
This report option is mutually exclusive with the COMPLETE, CONTINUE, and OVERLAID options. The MERGED option is intended for use with a REPORT form that is a sub-report (a REPORT form that another REPORT form calls) that specifies the same output file as the one that the main report (the calling REPORT form) specifies. The MERGED option merges the sub-report with the main report in the given output file, thereby producing a combined main report and sub-report. IAF prints the main reports page and column headings at the top of each report page and begins printing the main reports detail records on the first report page. If a main report record has one or more corresponding sub-report records, IAF prints the main reports record, followed by the sub-reports page and column headings, followed by the sub-report records that correspond to the main reports record. IAF prints the records from the main report even if there are no corresponding sub-report records.

Forms and Form Qualifiers IAF 8.0 DML

3-89

/OPTIONS

Following is the general syntactical format of a calling REPORT form (for example; a main report) and the REPORT form it calls (a sub-report), which specifies the MERGED option.
REPORT_FORM A & /TABLE=A & /SORTED_BY=(NAME) & /WITH=CUST_ID=AB . . OUTPUT_BLOCK ... . . BEGIN_BLOCK SUB_REPORT PERFORM B ! Instead of executing REPORT form B via a PERFORM ! statement, REPORT form A could use a /BREAK ! qualifier to execute it. END_BLOCK END_FORM REPORT_FORM B & /TABLE=B & /JOINED_TO=A & /SORTED_BY=(DATE) & /WITH=DATE < 31-DEC-1998 & /OPTIONS=MERGED . . OUTPUT_BLOCK ... . . END_FORM

3-90

Forms and Form Qualifiers IAF 8.0 DML

/OPTIONS

Here is an executable example that uses this general syntactical format, followed by an example page of the output report file it produces.
TITLE MOVIES,MOVIES REPORT REPORT_FORM MAIN & /READ_ONLY & /WIDTH=80 & /OUTPUT=(MOVIES_REPORT) & /TABLE=MOVIES & /LHEADING=(%NOW) & /RHEADING=(MASK(Page !-@@@@@, %PAGE)) & /HEADING=Movie Report OUTPUT_BLOCK MOVIE_ID /SOURCE=(MOVIES(MOVIE_ID)) OUTPUT_BLOCK MOVIE_TITLE /SOURCE=(MOVIES(MOVIE_TITLE)) OUTPUT_BLOCK PRICE /SOURCE=(MOVIES(PRICE)) OUTPUT_BLOCK TIMES_RENTED /SOURCE=(MOVIES(TIMES_RENTED)) BEGIN_BLOCK DO_SUB_REPORT PERFORM RENTAL_REPORT END_BLOCK OUTPUT_BLOCK SPACE_ONE /SOURCE=( ) END_FORM REPORT_FORM RENTAL_REPORT & /READ_ONLY & /WIDTH=80 & /COLUMN_SPACING & /OPTIONS=MERGED & /OUTPUT=(MOVIES_REPORT) & /TABLE=RENTALS & /JOINED_TO=MOVIES OUTPUT_BLOCK MEMBER_ID /SOURCE=(RENTALS(MEMBER_ID)) OUTPUT_BLOCK DATE_RENTED /SOURCE=(RENTALS(DATE_RENTED)) OUTPUT_BLOCK DATE_RETURNED /SOURCE=(RENTALS(DATE_RETURNED)) OUTPUT_BLOCK DAYS /SOURCE=(RENTALS(DAYS)) END_FORM

Forms and Form Qualifiers IAF 8.0 DML

3-91

/OPTIONS

6-DEC-1998 15:00:42:01 MOVIES REPORT Movie Movie Title ID ADV001 Indiana Jones Member ID BAB8912 GL_3848 ADV061 ADV586 Date Date Rented 17-NOV-1998 16-NOV-1998

Page 1 Times Price $1.50

Rented 2

Returned 18-NOV-1998 17-NOV-1998 $2.00 $1.00

Days R 1 1 46 7

Diamonds Are Forever Die Harder

Figure 3-8:MERGED Report Option Example

In this example, the main report prints information regarding each movie in the current inventory. For any movie that has been rented, the subreport prints to the same output file a list of the rental transactions that have taken place for the movie, preceded by the sub-reports column headings. No form feed precedes or follows printing of the sub-report information.

NOUNDERLINES
This report option causes IAF not to print a line of dashes below the column headings in a REPORT form. By default, IAF prints a line of dashes below each column heading.

OVERLAID NOTE:
This report option is mutually exclusive with the COMPLETE, CONTINUE, and MERGED options. The OVERLAID report option is intended for use with a REPORT form that is a sub-report (i.e. a REPORT form that another REPORT form calls) that specifies the same output file as the one that the main report (the calling REPORT form) specifies. The OVERLAID option merges the sub-report with the main report in the given output file, thereby producing a combined main report and sub-report. The OVERLAID report option differs from the MERGED report option in that by specifying the OVERLAID option, a sub-report can print its column headings on the same row as the main reports column headings. To do this, the sub-report must use the /COL qualifier to specify the column position in which the first sub-report column is to begin printing. The sub-report column headings overwrite any portion of the main report
3-92 Forms and Form Qualifiers IAF 8.0 DML

/OPTIONS

column headings that prints in the column that the sub-reports /COL qualifier specifies or in subsequent columns. IAF prints the column headings for the main report and the sub-report in the same row at the top of each report page and begins printing the main reports detail records on the first report page. If a main report record has any corresponding subreport records, IAF prints the main reports record, and then in the next row, begins printing the sub-reports records, with each record starting in the column that the sub-reports /COL qualifier specifies. Following is the general syntactical format of a calling REPORT form (i.e. a main report) and the REPORT form it calls (i.e. a sub-report), which specifies the OVERLAID option.
REPORT_FORM A & /TABLE=A /SORTED_BY=(NAME) /WITH=CUST_ID <> 000000 . . OUTPUT_BLOCK ... . . BEGIN_BLOCK SUB_REPORT PERFORM B ! Instead of executing REPORT form B via a PERFORM ! statement, REPORT form A could use a /BREAK ! qualifier to execute it. END_BLOCK END_FORM REPORT_FORM B & /TABLE=B & /JOINED_TO=A & /COL=55 & /SORTED_BY=(DATE) & /WITH=DATE > 31-DEC-1991 & /OPTIONS=OVERLAID . . OUTPUT_BLOCK ... . . END_FORM

Forms and Form Qualifiers IAF 8.0 DML

3-93

/OPTIONS

Following is an executable example that uses this general syntactical format, followed by an example page of the output report file it produces.
TITLE MOVIES,MOVIES_REPORT REPORT_FORM MAIN & /READ_ONLY & /WIDTH=80 & /OUTPUT=(MOVIES_REPORT) & /TABLE=MOVIES & /LHEADING=(%NOW) & /RHEADING=(MASK(Page !-@@@@@, %PAGE)) & /HEADING=Movie Report OUTPUT_BLOCK MOVIE_ID /SOURCE=(MOVIES(MOVIE_ID)) OUTPUT_BLOCK MOVIE_TITLE /SOURCE=(MOVIES(MOVIE_TITLE)) BEGIN_BLOCK DO_SUB_REPORT PERFORM RENTAL_REPORT END_BLOCK END_FORM REPORT_FORM RENTAL_REPORT & /READ_ONLY & /WIDTH=80 & /COL=35 & /OPTIONS=OVERLAID & /OUTPUT=(MOVIES_REPORT) & /TABLE=RENTALS & /JOINED_TO=MOVIES OUTPUT_BLOCK MEMBER_ID /SOURCE=(RENTALS(MEMBER_ID)) OUTPUT_BLOCK DATE_RENTED /SOURCE=(RENTALS(DATE_RENTED))
OUTPUT_BLOCK DATE_RETURNED /SOURCE=(RENTALS(DATE_RETURNED))

OUTPUT_BLOCK DAYS /SOURCE=(RENTALS(DAYS)) END_FORM

Figure 3-9: Overlaid Report Option Example

3-94

Forms and Form Qualifiers IAF 8.0 DML

/OPTIONS

PAGE_BREAK_REPRINT
This report option causes IAF to reprint, at the beginning of a new page, information that it would normally suppress due to a /BREAK qualifier on an output block. Following is an executable example that uses the PAGE_BREAK_REPRINT option, followed by example pages of the output report file it produces.
TITLE MEMBERS,MEMBERS REPORT REPORT_FORM MAIN & /READ_ONLY & /WIDTH=80 & /OPTIONS=PAGE_BREAK_REPRINT & /OUTPUT=MEMBERS_REPORT & /TABLE=MEMBERS & /SORTED_BY=MEMBERS(STATE) & /SORTED_BY=MEMBERS(CITY) & /BREAK=MEMBERS(STATE) & /BREAK=MEMBERS(CITY) & /LHEADING=(%NOW) & /RHEADING=(MASK(Page !-@@@@@, %PAGE)) & /HEADING=Video Plus & /HEADING=Members Report OUTPUT_BLOCK STATE /SOURCE=(MEMBERS(STATE)) & /BREAK=1 OUTPUT_BLOCK CITY /SOURCE=(MEMBERS(CITY)) & /BREAK=2 OUTPUT_BLOCK MEMBER_ID /SOURCE=(MEMBERS(MEMBER_ID)) OUTPUT_BLOCK LAST_NAME /SOURCE=(MEMBERS(LAST_NAME)) OUTPUT_BLOCK FIRST_NAME /SOURCE=(MEMBERS(FIRST_NAME)) END_FORM

Forms and Form Qualifiers IAF 8.0 DML

3-95

/OPTIONS

6-DEC-1998 14:33:32:51 VideoPlus MEMBERS REPORT Member Last ID name MLF89021 Beringer CAW91041 Carver PRT90122 Patterson BUR92093 Barlow MCD88322 Magoffin AJR39772 Anderson ALAe8263 Ames

Page 1

St City AZ Phoenix

Tuscon CA Escondido

First name Martin M. Andrew W. Rene T. Valerie R. Carl D. John R. Louie A. Page 2

6-DEC-1998 14:33:32:51 VideoPlus MEMBERS REPORT Member Last ID name MLF20852 Mercier MM_38829 McElroy MSM58493 Mathias NLB33911 Nunez

St City CA Escondido

First name Len F. Mary Susan N. Larry B.

Figure 3-10: PAGE_BREAK_REPRINT Report Option Example

It should be noted that if one logical row results in multiple physical output rows, the break values will not always be reprinted. If the output comprises elements on rows other than 1, the break values will be reprinted only if the page break occurs at the end of such output. When IAF begins to process a logical row, it must evaluate at that point whether or not break information is to be printed. If a page break subsequently occurs in the middle of the physical multi-row output, break values will not be reprinted. Consider an example where the output for each logical row is split over two lines:
OUTPUT_BLOCK STATE /SOURCE=(MEMBERS(STATE))/BREAK=1 /ROW=1 /COL=1 OUTPUT_BLOCK CITY /SOURCE=(MEMBERS(CITY)) /BREAK=2 /ROW=1 /COL=4

OUTPUT_BLOCK MEMBER_ID /SOURCE=(MEMBERS(MEMBER_ID)) /ROW=1 /COL=15 OUTPUT_BLOCK LAST_NAME /SOURCE=(MEMBERS(LAST_NAME)) /ROW=2 /COL=28 OUTPUT_BLOCK FIRST_NAME/SOURCE=(MEMBERS(FIRST_NAME))/ROW=2 /COL=50

Depending upon the page size and the value of any /END_ROW qualifier, a page throw could occur after row 2 had been successfully output for the

3-96

Forms and Form Qualifiers IAF 8.0 DML

/OPTIONS

current logical row. In that situation, the break values would be reprinted at the top of the next page. If, instead, the page throw occurred after only row 1 had been output, then no break values will be reprinted. Consider the following example, based on the earlier samples:
CA Escondido AJR39772 Anderson John R. ALAe8263 Ames Louie A.

If a page break occurs here, the new page will successfully reprint the break information.
CA Escondido AJR39772 Anderson John R. ALAe8263

If the page break occurs here instead, the break information will not be reprinted on the new page. The /END_ROW qualifier can be used to ensure that multi-row output is not split over two pages.

PRINT
This report option causes IAF to prompt the end user for the name of the print queue to which to send the report listing, the name of the form type to use when printing the report, and the number of report listings to print. IAF prompts for this information via the Queue Information window prior to processing the given report. Specifying zero copies results in IAF producing a report but not queuing the listing to any printer. This report option allows the end user to print the given report immediately upon performing the form, without having to use the File Manager utility.

SUMMARY
This report option is intended for use with the /BREAK form qualifier and the /TOTAL output block qualifier. This option causes IAF not to print detail records at the lowest level of detail (i.e. the records in the group that the REPORT forms last /BREAK qualifier specifies). Instead, IAF prints a row of summary data for each break group at the lowest level. The summary data consists of the given total(s) for the group.

Forms and Form Qualifiers IAF 8.0 DML

3-97

/OPTIONS

To print a single line of non-numeric data for a given group, you would use the /GROUPED_BY or /REDUCED_TO form qualifier instead of the /BREAK and /OPTIONS=SUMMARY form qualifiers. For details regarding the /TOTAL block qualifier, refer to this manuals BLOCKS AND BLOCK QUALIFIERS chapter. The following shows an executable example that uses the SUMMARY option, followed by an example page of the output file it produces.
TITLE MOVIES,MOVIES REPORT REPORT_FORM MAIN & /READ_ONLY & /WIDTH=80 & /OPTIONS=SUMMARY & /OUTPUT=(MOVIES_REPORT) & /TABLE=MOVIES,MOVIE_TYPES & /SORTED_BY=MOVIES(MOVIE_TYPE) & /BREAK=(MOVIES(MOVIE_TYPE)) & /LHEADING=(%NOW) & /RHEADING=(MASK(Page !-@@@@@, %PAGE)) & /HEADING=(Movie Type Summary Report) OUTPUT_BLOCK DESCRIPTION /SOURCE=(MOVIE_TYPES(DESCRIPTION)) OUTPUT_BLOCK TIMES_RENTED /SOURCE=(MOVIES(TIMES_RENTED)) & /TOTAL OUTPUT_BLOCK REVENUE & /SOURCE=(MOVIES(PRICE) * MOVIES(TIMES_RENTED)) & /USING=(MOVIES(PRICE)) & /TOTAL & /HEADING=Total,Revenue END_FORM

6-DEC-1998 14:33:32:51 Movie Type Summary Times Rented 55 60 10 69 194 Figure 3-11: SUMMARY Report Option Example Total Revenue $102.00 $135.00 $10.00 $138.00 $385.00

Page 1

Description Adventure Comedy Romance Science Fiction

3-98

Forms and Form Qualifiers IAF 8.0 DML

/OPTIONS

ZEROSUPPRESS
This report option causes IAF to suppress the printing of any report record for which all output blocks that specify the /TOTAL qualifier have zero values. Following is an executable example that uses the ZEROSUPPRESS option, followed by sample data and the output that the example produced based upon that data.
TITLE MOVIES,MOVIES REPORT REPORT_FORM MAIN & /READ_ONLY & /WIDTH=80 & /OPTIONS=ZEROSUPPRESS & /OUTPUT=(MOVIES_REPORT) & /TABLE=MOVIES & /SORTED_BY=MOVIES(MOVIE_TYPE) & /LHEADING=(%NOW) & /RHEADING=(MASK(Page !-@@@@@, %PAGE)) & /HEADING=(Rented Movies) OUTPUT_BLOCK MOVIE_ID /SOURCE=(MOVIES(MOVIE_ID)) OUTPUT_BLOCK MOVIE_TITLE /SOURCE=(MOVIES(MOVIE_TITLE)) OUTPUT_BLOCK TIMES_RENTED /SOURCE=(MOVIES(TIMES_RENTED)) & /TOTAL OUTPUT_BLOCK PRICE /SOURCE=(MOVIES(PRICE)) OUTPUT_BLOCK REVENUE & /SOURCE=(MOVIES(PRICE) * MOVIES(TIMES_RENTED)) & /USING=(MOVIES(PRICE)) & /TOTAL & /HEADING=Total,Revenue END_FORM

Forms and Form Qualifiers IAF 8.0 DML

3-99

/OPTIONS

Figure 3-12: MOVIES Table Sample Data

Figure 3-13: ZEROSUPPRESS Report Option Example

In this example, the report does not print the record for The World According to Garp because its value for the two total columns (Times Rented and Total Revenue) is zero.

3-100

Forms and Form Qualifiers IAF 8.0 DML

/OPTIONS

For TABLE_EDIT forms:

This qualifier allows you to specify table edit option keywords to change the default behavior of a TABLE_EDIT form. You may specify the table edit options in any logical combination. The table on the following page lists and describes the option keywords that are valid for use with the /OPTIONS qualifier on a TABLE_EDIT form. Table Edit Option Keywords Keyword AUDIT DISPLAY_RO Description Makes TED and QBF perform data auditing on all table fields by default. This option causes a read-only transaction to start during the display phase of the TABLE_EDIT form. By default, IAF starts a read-write transaction for each row of data. This option minimizes the occurrence of data contention problems during a TABLE_EDIT forms initial display phase by allowing IAF to display selected records in the TABLE_EDIT form even if the records are write-locked. This option works only if the SET LOCK TED_LINE option is in use and no transaction is in progress when the TABLE_EDIT form executes. Also note that using the TED_LINE lock option may result in the TABLE_EDIT form displaying data that is no longer current (if data updates take place during or after the display phase). For details regarding the TED_LINE lock option, refer to the description of the SET LOCK statement in this manuals LANGUAGE STATEMENTS chapter. EXIT_EMPTY This option causes the TABLE_EDIT form to exit immediately and to return a %EMPTY status if no records matching the given criteria exist. No screen output takes place when a %EMPTY exit takes place. For details regarding %EMPTY, refer to this manuals SPECIAL VARIABLES AND VALUE SYMBOLS chapter.

Forms and Form Qualifiers IAF 8.0 DML

3-101

/OPTIONS

Table Edit Option Keywords Keyword FAST_INSERT Description This option minimizes the amount of screen updating that takes place when performing batch entry via a TABLE_EDIT form. In general, screen management routines consume the majority of CPU time during batch entry. In some cases, it is possible to improve CPU performance by as much as 30% via this option. This option forces the TABLE_EDIT forms display row height and input row height to be equal, and causes IAF to display only the background of the current field in the selected input row (instead of all field backgrounds). Additionally, IAF does not redisplay the input row after the end-user completes all entries for the row. This means that any computed fields do not redisplay, and therefore do not show their computed values. However, it is possible to explicitly perform the necessary computations via the TABLE_EDIT forms DML code and then display the result. INSERT_FIRST This option indicates that when the TABLE_EDIT form executes, it is to place the end user directly into INSERT mode at the top of the form. This option indicates that the TABLE_EDIT form is to allow record insertions to take place only at the bottom of the form. Attempting to insert a record elsewhere causes IAF to display an error message indicating that insertions are to take place at the end of the form.

INSERT_END

3-102

Forms and Form Qualifiers IAF 8.0 DML

/OPTIONS

Table Edit Option Keywords Keyword MENU Description This option indicates that IAF is to perform the TABLE_EDIT form as a menu, and causes the form to have the following characteristics: A reverse video selection bar highlights the current row, and moves up and down with the cursor. The form exits when the end user selects a row by placing the cursor on the desired row and pressing the GM_SELECT_ROW key. Exiting the form with a selected row writes the record that the row represents to the user buffer for subsequent program use if a transaction that was started outside the TABLE_EDIT form is currently outstanding. Otherwise, IAF blanks the user buffer when the form exits because its transaction is complete. The MENU option implies that the records in the TABLE_EDIT form are read-only records (for example; the end user cannot perform modifications, insertions, or deletions to the records.) NODELETE NOEDIT This option indicates that the TABLE_EDIT form is not to allow the deletion of lines. This option indicates that the TABLE_EDIT form is to display the selected records on the screen and then automatically exit. When using this option, it is possible to keep the TABLE_EDIT form displayed on the screen by appending the /REMAIN qualifier to the given TABLE_FORM statement. This option indicates that the TABLE_EDIT form is not to allow the addition of lines. This option indicates that the TABLE_EDIT form is not to allow the selection of lines for modification.

NOINSERT NOMODIFY

Forms and Form Qualifiers IAF 8.0 DML

3-103

/OPTIONS

Table Edit Option Keywords Keyword POSITION_AT_END Description This option causes the TABLE_EDIT form to display the last available screen of information and position the cursor on the End line in the form. If the TABLE_EDIT form does not specify this option, the default behavior is to display the first screen of information and position the cursor on the first row. Using this option in conjunction with the INSERT_END option positions the cursor at the end of the TABLE_EDIT form to enable the end user to append records immediately upon entering the form. This option indicates that when the TABLE_EDIT form executes, it is to automatically select each row in turn. Upon selecting the last row, the form exits. This option prevents the end user from being able to move the cursor up and down the screen to select individual rows. This option indicates that the TABLE_EDIT form is to exit immediately without any screen interaction if only a single row is available for selection, and is typically used in conjunction with the MENU option. IAF writes the record that the single row represents to the user buffer just as it would if only the MENU option was active and an end user selected the row. This option is intended for use with the /FIND_FORM qualifier, and causes IAF to display records in the TABLE_EDIT form after executing the form that the /FIND_FORM qualifier specifies. By default, IAF displays the TABLE_EDIT forms records first. Then, if the end user presses the GM_FIND_ROW key, IAF executes the form that the /FIND_FORM qualifier specifies. The START_FIND option allows the end user to enter search criteria before IAF displays the selected record set. For details regarding the /FIND_FORM qualifier, refer to its description in this chapter.

SELECT_ALL

SELECT_ONE

START_FIND

3-104

Forms and Form Qualifiers IAF 8.0 DML

/OUTPUT

/OUTPUT
Syntax
/OUTPUT=expression

Description
This qualifier allows you to specify the name of the file to which to write a REPORT forms output. The given expression must be a valid file specification. IAF uses a default filetype of .lis. In the absence of this qualifier, IAF uses a default filename of table_name.lis, where table_name is the name of the first table that the REPORT forms /TABLE qualifier specifies.

Example
/OUTPUT=MOVIES_REPORT

Forms and Form Qualifiers IAF 8.0 DML

3-105

/PDF

/PDF
Syntax
/PDF=(option=value[, option=value[,...]])

Description
This qualifier applies to REPORT forms and to the OPEN_TEXT/CREATE statement. The PDF qualifier has many options. The entire option list as a whole should be enclosed in parenthesis. Each option value may be a quoted string, a variable, or an expression containing table-field references, functions, operators, etc. Some options require textual input and others require numeric input. For numeric values, unless otherwise stated, both integer and floating point values are accepted. Please refer to the PDF Reports and PDF file production section of this document for more information concerning IAF and PDF production.

Options
AUTHOR=author-text This option permits the specification of a 1-256 character (character, not byte) textual source containing the author setting for the document. CELLWIDTH=cell-width-number This option sets the character cell width for positioning report columns on the page. The option value must be a number or a numeric source. Both integer and floating point numbers are acceptable. The cell width is specified as a percentage of the font size. For fixed width Adobe Core fonts, the default cell width is 100 percent of the font width and should not normally be changed. For proportional Adobe Core fonts, the default cell width is 120 percent of the average character width in the font. For all other fonts, the default cell width is 100 percent of the font size (which is extremely pessimistic). Cellwidth can be used with proportional fonts to adjust the amount of space dedicated to each column so that it is neither too optimistic nor too pessimistic. For example, cellwidth=130 sets the cell width to 130 percent of the font size.

3-106

Forms and Form Qualifiers IAF 8.0 DML

/PDF

COLOR=color-option-list This option sets the color of text and lines shown in the document. Coloroption-list is a textual source containing a comma separated list of color options. The following color options may be used: FILL=color and STROKE=color. FILL and STROKE set the colors for the portions of the text rendered as described below for the RENDER option. Note that when using proportional fonts, the lines drawn in the column headers are also rendered as strokes. For example: COLOR=FILL=BLUE, STROKE=ORANGE. The default is FILL=BLACK,STROKE=BLACK. Colors must be selected from the following list: AliceBlue AntiqueWhite Aqua Aquamarine Azure Beige Bisque Black BlanchedAlmond Blue BlueViolet Brown BurlyWood CadetBlue Chartreuse Chocolate Coral CornflowerBlue Cornsilk Crimson Cyan DarkBlue DarkCyan DarkGoldenRod DarkGray DarkGreen DarkKhaki DarkMagenta DarkOliveGreen

Forms and Form Qualifiers IAF 8.0 DML

3-107

/PDF

Darkorange DarkOrchid DarkRed DarkSalmon DarkSeaGreen DarkSlateBlue DarkSlateGray DarkTurquoise DarkViolet DeepPink DeepSkyBlue DimGray DodgerBlue Feldspar FireBrick FloralWhite ForestGreen Fuchsia Gainsboro GhostWhite Gold GoldenRod Gray Green GreenYellow HoneyDew HotPink IndianRed Indigo Ivory Khaki Lavender LavenderBlush LawnGreen LemonChiffon LightBlue LightCoral LightCyan LightGoldenRodYellow LightGrey LightGreen

3-108

Forms and Form Qualifiers IAF 8.0 DML

/PDF

LightPink LightSalmon LightSeaGreen LightSkyBlue LightSlateBlue LightSlateGray LightSteelBlue LightYellow Lime LimeGreen Linen Magenta Maroon MediumAquaMarine MediumBlue MediumOrchid MediumPurple MediumSeaGreen MediumSlateBlue MediumSpringGreen MediumTurquoise MediumVioletRed MidnightBlue MintCream MistyRose Moccasin NavajoWhite Navy OldLace Olive OliveDrab Orange OrangeRed Orchid PaleGoldenRod PaleGreen PaleTurquoise PaleVioletRed PapayaWhip PeachPuff Peru

Forms and Form Qualifiers IAF 8.0 DML

3-109

/PDF

Pink Plum PowderBlue Purple Red RosyBrown RoyalBlue SaddleBrown Salmon SandyBrown SeaGreen SeaShell Sienna Silver SkyBlue SlateBlue SlateGray Snow SpringGreen SteelBlue Tan Teal Thistle Tomato Turquoise Violet VioletRed Wheat White WhiteSmoke Yellow YellowGreen

CREATOR=creator-text This option permits the specification of a 1-256 character textual source containing the creator (AKA application name) setting for the document. ENCODING=encoding-name-text This option specifies the document encoding. An encoding should only be specified when using a CJK font. IAF automatically supplies the correct

3-110

Forms and Form Qualifiers IAF 8.0 DML

/PDF

encoding when using any of the Adobe standard CJK fonts listed below under font-name-text. Therefore an encoding need not be specified when using an Adobe standard CJK font. This option is mostly designed for future use. The following encoding names are accepted: Unicode, UniGB-UTF16-H, UniCNS-UTF16-H, UniJIS-UTF16-H, UniKSUTF16-H. The encoding name is not case sensitive. FONTNAME=font-name-text This option sets the name of a font that exists on both the machine where the document is being produced and on all machines where the document will be viewed. (However, PDFlib will embed the font in the document.) For maximal portability, it is highly recommended to specify either an Adobe Core Font or an Adobe Standard CJK font. Further, for column alignment purposes, it is recommended to specify a fixed font (such as Courier). The font name is not case sensitive. The Adobe Core Fonts are: Courier, Courier-Bold, Courier-Oblique, Courier-BoldOblique, Helvetica, Helvetica-Bold, Helvetica-Oblique, Helvetica-BoldOblique, Times-Roman, Times-Bold, Times-Italic, TimesBoldItalic, Symbol, and ZapfDingbats. The Adobe Standard CJK Fonts are: STSong-Light, STSongStd-LightAcro, AdobeSongStd-Light-Acro, MHei-Medium, MSung-Light, MSungStd-Light-Acro, AdobeMingStd-Light-Acro, HeiseiKakuGo-W5, HeiseiMin-W3, KozMinPro-Regular-Acro, KozGoPro-Medium-Acro, HYGoThic-Medium, HYSMyeongJo-Medium, HYSMyeongJoStdMedium-Acro, AdobeMyungjoStd-Medium-Acro. If the font name is not specified and GEM_CHARACTER_SET is set to a Chinese, Japanese or Korean character set, then an appropriate Adobe Standard CJK font from the above list will be used as the default font otherwise the default font is Courier. FONTSIZE=font-size-number This option sets the size of the font in points where a point is 1/72 of an inch. This option must be a number or a numeric source. Both integer and floating point numbers are acceptable. If the font size is not specified, but a page size is specified, then the font size is set such that the appropriate number of rows (GEM_LP_LINES or SYS$LP_LINES, depending on your server platform) fit on the page. In this case the horizontal width of the font may also be scaled if the width of the report would otherwise cause it to exceed the width of the page. The default font size is 12, which

Forms and Form Qualifiers IAF 8.0 DML

3-111

/PDF

is also subject to being scaled to fit the page. To prevent font scaling, specify an explicit font size and an explicit page size. KEYWORDS=keywords-text This option permits the specification of a 1-256 character (character not byte) textual source containing a space separated list of key words to be associated with the PDF document. For example, keywords=word1 word2 word3. LANGUAGE=language-text This option is a text string that specifies the document language with a language identifier having the syntax defined in Internet RFC 3066, Tags for the Identification of Languages. This syntax, which is summarized below, is also used to identify languages in XML, according to the W3C document Extensible Markup Language (XML) 1.1. An empty string indicates that the language is unknown. Language identifiers can be based on codes defined by the International Organization for Standardization in ISO 639 and ISO 3166 or registered with the Internet Assigned Numbers Authority (IANA, whose Web site is located at <http://iana.org/>), or they can include codes created for private use. A language identifier consists of a primary code optionally followed by one or more subcodes (each preceded by a hyphen). The primary code can be any of the following: A 2-character ISO 639 language code example, en for English or es for Spanish. The letter i, designating an IANA-registered identifier. The letter x, for private use. The first subcode can be a 2-character ISO 3166 country code, as in enUS, or a 3- to 8-character subcode registered with IANA, as in encockney or i-cherokee (except in private identifiers, for which subcodes are not registered). Subcodes beyond the first can be any that have been registered with IANA. Note that GEMBASE does not validate the language. The language text string is placed directly into the resulting PDF files Document Catalog as-is. MARGINS=margin-text This option permits the page margins to be set. The following comma separated margin options may be specified:

3-112

Forms and Form Qualifiers IAF 8.0 DML

/PDF

LEFT=left-margin-text - Establishes a margin on the left side of the page. RIGHT=right-margin-text - Establishes a margin on the right size of the page. TOP=top-margin-text - Establishes a margin at the top of the page. BOTTOM=bottom-margin-text - Establishes a margin at the bottom of the page. CLIP - Causes the text to be clipped at the right and bottom margins. Each margin is specified using a number optionally followed by a measure. The margin can be specified in inches, centimeters, millimeters or points (where a point is 1/72 of an inch) using the suffixes in, cm, mm and pt respectively. If no suffix is specified, inches are assumed. Floating point numbers with decimal digits (but not scientific notation with exponents) may be used. For example: Margins=Left=10mm, Right=1cm, Top=0.5in, Bottom=0.5in. Note that the margins affect page sizing, font sizing and horizontal scaling when an explicit page size is specified, but no font size is specified or when an explicit font size is specified, but no page size is specified. In both cases GEMBASE scales the output to fit within the specified margins. Note that the right and bottom margins do not establish clipping zones unless the clip option is specified. Without the clip option, text is clipped only by the edge of the page. With the clip option, text is clipped at the margins. MONOSPACE=monospace-number This option specifies an integer source which indicates the desired width for all glyphs. Monospace is based on a 1000 unit per character grid, is only intended to be used in combination with the Adobe Standard CJK fonts and should not be used with other fonts. A monospace value of 1000 generally produces pleasing results. Monospace defaults to 1000 for standard CJK fonts. OWNER_PASSWORD=owner-password-text This option permits the specification of a 1-32 character textual source containing the owner password for the document. Once the document has been created, knowledge of the owner password will be required to alter either the user password or the document permissions. The owner password is sometimes also referred to as the master password.

Forms and Form Qualifiers IAF 8.0 DML

3-113

/PDF

PAGELAYOUT=page-layout-text This option determines the page layout to be used when the document is opened. Note that different viewer applications may interpret this option differently than described here. The actual interpretation is determined by the viewer. What follows is the interpretation that is defined in the Adobe PDF Reference Manual. One of the following page layouts may be specified: SinglePage - Display one page at a time. This is the default. OneColumn - Display the pages in one column. TwoColumnLeft - Display the pages in two columns, with odd numbered pages on the left. TwoColumnRight - Display the pages in two columns, with odd numbered pages on the right. TwoPageLeft - Display the pages two at a time, with odd-numbered pages on the left. TwoPageRight - Display the pages two at a time, with oddnumbered pages on the right.

PAGEMODE=page-mode-text This option specifies how the document should be displayed when opened: Note that different viewer applications may interpret this option differently than described here. The actual interpretation is determined by the viewer. What follows is the interpretation that is defined in the Adobe PDF Reference Manual. One of the following page modes may be specified: UseNone - Neither document outline nor thumbnail images visible. This is the default. UseOutlines - Document outline visible. UseThumbs - Thumbnail images visible. FullScreen - Full-screen mode, with no menu bar, window controls, or any other window visible. UseOC - Optional content group (layers) panel visible. UseAttachments - Attachments panel visible.

3-114

Forms and Form Qualifiers IAF 8.0 DML

/PDF

PAGESIZE=pagesize-option-list This option specifies a textual source that sets the page size and optionally the page format. If the optional page format is specified, the page size and page format are separated with a comma. The order is important; the page size must come first followed by an optional page format. Two page formats are available. These are LANDSCAPE and PORTRAIT. By default all pages are PORTRAIT format. That is, the height dimension is larger than the width dimension. To swap the height and width dimensions, specify LANDSCAPE as the page format. Examples: a4,landscape, letter,landscape. The page size is not case sensitive. By default DML calculates an appropriate page size from the reports height, width and font size. Although the calculated page size in this situation might appear perfectly natural when viewed on the screen, it might not fit any real physical paper size. To avoid that situation, specify an explicit page size. Page sizes may be specified by name from the list below or by arbitrary dimensions. The syntax for specifying arbitrary dimensions is described further below. Acceptable named page sizes with their corresponding equivalent dimensions in millimeters and points or inches and points are as follows:

Table 1: Pagesize
4A0 2A0 A0 A1 A2

Dimensions
1682 x 2378 mm 1189 x 1682 mm 841 x 1189 mm 594 x 841 mm 420 x 594 mm

Point Width
4767.8740 3370.3937 2383.9370 1683.7795 1190.5512

Point Height
6740.7874 4767.8740 3370.3937 2383.9370 1683.7795

Forms and Form Qualifiers IAF 8.0 DML

3-115

/PDF

Table 1: Pagesize
A3 A4 A5 A6 A7 A8 A9 A10 4B0 2B0 B0 B1 B2 B3 B4 B5

Dimensions
297 x 420 mm 210 x 297 mm 148 x 210 mm 105 x 148 mm 74 x 105 mm 52 x mm 37 x mm 26 x mm 74 52 37

Point Width
841.8898 595.2756 419.5276 297.6378 209.7638 147.4016 104.8819 73.7008 5669.2913 4008.1890 2384.6457 2004.0945 1417.3228 1000.6299 708.6614 498.8976

Point Height
1190.5512 841.8898 595.2756 429.5276 297.6378 209.7638 147.4016 104.8819 8016.3780 5669.2913 4008.1890 2384.6457 2004.0945 1417.3228 1000.6299 708.6614

2000 x 2828 mm 1414 x 2000 mm 1000 x 1414 mm 707 x 1000 mm 500 x 707 mm 353 x 500 mm 250 x 353 mm 176 x 250 mm

3-116

Forms and Form Qualifiers IAF 8.0 DML

/PDF

Table 1: Pagesize
B6 B7 B8 B9 B10 C0 C1 C2 C3 C4 C5 C6 C7 C8 C9 C10

Dimensions
125 x 176 mm 88 x 125 mm 62 x mm 44 x mm 31 x mm 88 62 44

Point Width
354.3307 249.4488 175.7480 124.7244 87.8740 2599.3781 1836.8504 1298.2677 918.4252 649.1339 459.2126 323.1496 229.6063 161.5748 113.3859 79.3701

Point Height
498.8976 354.3307 249.4488 175.7480 124.7244 3676.5354 2599.3701 1836.8504 1298.2677 918.4252 649.1339 459.2126 323.1496 229.6063 161.5748 113.3858

917 x 1297 mm 648 x 917 mm 458 x 648 mm 324 x 458 mm 229 x 324 mm 162 x 229 mm 114 x 162 mm 81 x 114 mm 57 x mm 40 x mm 28 x mm 81 57 40

Forms and Form Qualifiers IAF 8.0 DML

3-117

/PDF

Table 1: Pagesize
JISB0 JISB1 JISB2 JISB3 JISB4 JISB5 JISB6 JISB7 JISB8 JISB9 JISB10 EXECUTIV E LETTER LEGAL LEDGER

Dimensions
1030 x 1456 mm 728 x 1030 mm 515 x 728 mm 364 x 515 mm 257 x 364 mm 182 x 257 mm 128 x 182 mm 91 x 128 mm 64 x mm 45 x mm 32 x mm 91 64 45

Point Width
2919.6850 2063.6220 1459.8425 1031.8110 728.5039 498.8976 354.3307 257.9528 181.4173 127.5591 87.8740 540.0000 612.0000 612.0000 1224.0000

Point Height
4127.2441 2919.6850 2063.6220 1459.8425 1031.8110 728.5039 498.8976 354.3307 257.9528 181.4173 127.5991 720.0000 792.0000 1008.0000 792.0000

7.5 x 10 inches 8.5 x 11 inches 8.5 x 14 inches 11 x 17 inches

In addition to a page size name from the above list, the page size may also be specified by arbitrary dimensions using the form #x# where the
3-118 Forms and Form Qualifiers IAF 8.0 DML

/PDF

number on the left of the X is the page width and the number on the right of the X is the page height. The width and height in inches, centimeters, millimeters or points (where a point is 1/72 of an inch) can be specified with the suffixes in, cm, mm and pt respectively. If no suffix is specified, inches are assumed. Floating point numbers with decimal digits (but not scientific notation with exponents) may be used. Examples: 8.5x11, 11x17,portrait, 279.45mmx431.72mm, 612.987ptx1224.5678pt,landscape. The report output will be scaled or cropped whenever an explicitly specified page size is not large enough to contain the actual report page output. However, this depends on whether an explicit font size was specified. Cropping will occur if an explicit font size was specified. Scaling will occur if an explicit font size was not specified. PERMISSIONS=permissions-option-list This option specifies a textual source containing a comma separated list of access restriction keywords. When using the permissions option, the owner password option must also be set -- otherwise Acrobat users could easily remove the permission settings. By default, all actions are allowed. Specifying an access restriction disables the respective feature in Acrobat. Access restrictions can be applied without specifying a user password. Multiple restriction keywords can be specified as in the following example: permissions=noprint, nocopy Keyword Noprint Nomodify Explanation Acrobat will prevent printing the file. Acrobat will prevent users from adding form fields or making any other changes. Acrobat will prevent copying and extracting text or graphics, and will disable the accessibility interface Acrobat will prevent adding or changing comments or form fields. Acrobat will prevent form field filling, even if noannots hasnt been specified.

Nocopy

Noannots Noforms

Forms and Form Qualifiers IAF 8.0 DML

3-119

/PDF

Keyword Noaccessible

Explanation Acrobat will prevent extracting text or graphics for accessibility purposes (such as a screen reader program) Acrobat will prevent inserting, deleting, or rotating pages and creating bookmarks and thumbnails, even if nomodify hasnt been specified Acrobat will prevent high-resolution printing. If noprint hasnt been specified printing is restricted to the print as image feature which prints a low-resolution rendition of the page. Keep document metadata unencrypted even for encrypted documents.

Noassemble

Nohiresprint

Plainmetadata

RENDER=render-option-list This option specifies a textual source that contains a comma separated list of text rendering options that determine how text is rendered on the page. Text can be stroked, filled or both stroked and filled. The two rendering options which control this behavior are FILL and STROKE. Examples: RENDER=FILL, RENDER=STROKE or RENDER=FILL, STROKE. The default is RENDER=FILL. Note that while filled texts are pleasing to the eye, stroked texts and stroked and filled texts are generally not pleasing to the eye unless large font sizes are also specified. Rendering Fill Stroke Fill, Stroke Appearance Text is filled with a color. Text is outlined. Text is outlined and filled.

ROTATE=rotation-angle-integer This option specifies an integer source which contains the angle to which the text on the page should be rotated. Only the exact integer values 0, 90, 180 and 270 may be used. The default is 0 or no rotation. 90 and 270 produce text that displays sideways in Adobe Reader. 180 produces text that displays upside down. Although the reader of the document can
3-120 Forms and Form Qualifiers IAF 8.0 DML

/PDF

later select a menu item to re-rotate the text back to a normal viewing angle, this option should not be used if the document will be mostly viewed rather than printed. SUBJECT=subject-text This option permits the specification of a 1-256 character (character, not byte) textual source containing the subject setting for the document. TITLE=title-text This option permits the specification of a 1-256 character (character, not byte) textual source string containing the title setting for the document. USER_PASSWORD=user-password-text This option permits the specification of a 1-32 character textual source containing the user password for the document. Knowledge of either the user password or the owner password is required to open the document. VIEWER_PREFERENCES=viewer-preferences-text This option is a comma separated list of viewer preferences that control the way the document is to be presented on the screen or in print. If this option is not specified, viewing and printing applications behave in accordance with their own current user preference settings. Note that different viewer applications may interpret these preferences differently than described here. The actual interpretation is determined by the viewer. What follows is the interpretation that is defined in the Adobe PDF Reference Manual. The following comma separated viewer preference options may be specified: HideToolBar - Hide the viewer application tool bars when the document is active. HideMenuBar - Hide the viewer application menu bar when the document is active. HideWindowUI - Hide user interface elements in the document window (such as scroll bars and navigation controls), leaving only the document contents displayed. FitWindow - Resize the document to fit the size of the first displayed page.

Forms and Form Qualifiers IAF 8.0 DML

3-121

/PDF

CenterWindow - Position the document's window in the center of the screen. DisplayDocTitle - The Windows title bar should display the document title taken from the Title option. If not specified, then the title bar should instead display the name of the PDF file containing the document. NonFullScreenPageMode=non-full-screen-page-mode This specifies how to display the document upon exiting full-screen mode. One of the following non full screen page modes may be specified: UseNone - Neither document outline nor thumbnail are images visible. This is the default. UseOutlines - The document outline is visible. UseThumbs - Thumbnail images are visible. UseOC - The optional content group (layers) panel is visible. This entry is meaningful only if the value of the PageMode option is "FullScreen"; it is ignored otherwise.

3-122

Forms and Form Qualifiers IAF 8.0 DML

/READ_ONLY

/READ_ONLY
Syntax
/READ_ONLY

Description
This qualifier indicates that transactions that the given form starts are to be read-only. The forms type determines the exact action that will take place as a result of including the /READ_ONLY qualifier.

For TABLE_EDIT forms:

Appending this qualifier to a TABLE_FORM statement prevents the end user from modifying the TABLE_EDIT forms records and causes the forms DML code to execute for each record that the form displays as if an end user had selected each record. For details on attached block DML code, refer to the Introduction to Blocks and Block Qualifiers section in this manuals BLOCKS AND BLOCK QUALIFIERS chapter.

For All Forms:

This qualifier causes any real transaction started within the form to be read-only. By default, transactions are read-write. A real transaction differs from a pseudo transaction in that a real transaction is a first transaction. A pseudo transaction is a transaction started within the context of another transaction. For details on transactions, refer to the IAF Users Guide. The /READ_ONLY qualifier remains in effect for any forms that the current form performs. Therefore, any transaction that begins in a form that the current form performs is read-only unless it begins as the result of explicitly executing the START_TRANSACTION statement. For details on the START_TRANSACTION statement, refer to this manuals LANGUAGE STATEMENTS chapter.

Forms and Form Qualifiers IAF 8.0 DML

3-123

/REDUCED_TO

/REDUCED_TO
Syntax
/REDUCED_TO=(field_name[,...])

or
/REDUCED_TO=(table_name(field_name)[,...])

or
/REDUCED_TO=(context.field_name[,...])

or
/REDUCED_TO=(#variable_name[,...])

Description
This qualifier ensures that each fields value is unique for the selected record set, and facilitates summary selection operations. IAF selects a record to represent the set. If the given forms record selection criteria specifies more than one table, the /REDUCED_TO qualifier must prefix the names of fields from the second and subsequent tables by the name of the table in which they reside. The /REDUCED_TO qualifiers syntax permits the use of context variables in place of table names. Context variables are letter designations that IAF sequentially assigns to the tables that a forms /TABLE qualifier specifies. The first table that the /TABLE qualifier specifies is A, the second is B, and so on. Context variables are useful when performing a complex reduction operation. Such an operation might reference multiple tables. For example, suppose a given form header statement includes a /TABLE=X,Y,X qualifier and a /REDUCED_TO qualifier that references table fields X(FIELD1), Y(FIELD2), and X(FIELD2). The /REDUCED_TO qualifier can use context variables to differentiate between the two occurrences of the table X as the following example illustrates:
/REDUCED_TO=(A.FIELD1,B.FIELD2,C.FIELD2)

3-124

Forms and Form Qualifiers IAF 8.0 DML

/REDUCED_TO

The /REDUCED_TO qualifiers syntax also permits the use of one or more variables indicating the name(s) of the table field(s) for which to reduce the record set. The /REDUCED_TO qualifier is similar to the /GROUPED_BY qualifier. However, unlike the /GROUPED_BY qualifier which maintains access to all selected records, the /REDUCED_TO qualifier maintains access only to the representative record. For details regarding the /GROUPED_BY qualifier, refer to its description in this chapter. A form header statement may include multiple /REDUCED_TO qualifiers. Specifying multiple /REDUCED_TO qualifiers is equivalent to specifying one /REDUCED_TO qualifier with multiple reduced to clauses.

Examples
/REDUCED_TO=(DEPARTMENT)

This example causes IAF to return information once for each department.
/REDUCED_TO=(DEPARTMENT,SALES_ORDERS(ORDER_DATE))

This example causes IAF to return information once for each unique department/order date combination.
/REDUCED_TO=(CUSTOMERS(CUSTOMER_ID))

Forms and Form Qualifiers IAF 8.0 DML

3-125

/REDUCED_TO

This example causes IAF to return information once for each unique customer ID.
/REDUCED_TO=(#CUST_ID)

Assuming that the #CUST_ID variable holds the value A.CUSTOMER_ID, where the CUSTOMERS table is the first table that the /TABLE qualifier specifies, this example causes IAF to return information once for each unique value of CUSTOMERS(CUSTOMER_ID).
/REDUCED_TO=(A.CUSTOMER_ID,B.ORDER_DATE)

Assuming that the CUSTOMERS table is the first table that the /TABLE qualifier specifies and the SALES_ORDERS table is the second table that the /TABLE qualifier specifies, this example returns information once for each unique CUSTOMERS(CUSTOMER_ID)/SALES_ORDERS(ORDER_DATE) value combination.

3-126

Forms and Form Qualifiers IAF 8.0 DML

/REMAIN

/REMAIN
Syntax
/REMAIN

Description
This qualifier causes the given forms window to remain on the screen when the form exits (if the form was not the first form that the program executed). The forms window remains on the screen until the next highest calling form having no /REMAIN qualifier exits. The /REMAIN qualifier has no effect on the first form that a DML program executes because when that form exits, the DML program ends, thereby causing IAF to remove all subordinate forms. By default, when a form exits, IAF removes the forms window from the screen. You can specify the number of window images that can remain on the screen at one time via the SET SHADOWS statement. The SET SHADOWS statement directs IAF to remove the oldest window image when the number of images on screen reaches the set limit. Specifying a value of zero with the SET SHADOWS statement effectively disables the /REMAIN qualifier. For details on the SET SHADOWS statement, refer to this manuals LANGUAGE STATEMENTS chapter. If a calling form places an INPUT, YESNO, or PAUSE block within the screens last three lines, and an input error occurs at the block, causing IAF to display an error message, IAF redisplays the calling form so that the error message no longer occludes the block. However, IAF does not redisplay any called form whose header statement includes the /REMAIN qualifier. Therefore, do not place a forms INPUT, YESNO, or PAUSE block within the screens last three lines if the form calls a form that uses the /REMAIN qualifier.

Forms and Form Qualifiers IAF 8.0 DML

3-127

/REMAIN

Example
FORM A . PERFORM B . . END_FORM FORM B /REMAIN . PERFORM C . . END_FORM FORM C /REMAIN . . END_FORM

During form Cs execution, the screen displays three forms (i.e. one for each of forms A, B, and C). When form C exits, its window remains on the screen. When form B exits, form Bs window also remains on the screen. However, form A has no /REMAIN qualifier, and upon exiting, causes IAF to remove all subordinate form window images from the screen. Therefore, the screen no longer displays form Bs image or form Cs image after form A exits.

3-128

Forms and Form Qualifiers IAF 8.0 DML

/REPEAT

/REPEAT
Syntax
/REPEAT[=NOCLEAN]

Description
This qualifier causes IAF to execute the given form repeatedly until it exits with a non-normal exit status (e.g. the end user presses the GM_EXIT key). You can use this qualifier to reiterate execution of a NORMAL form and enable the end user to continuously enter data via the forms window. IAF displays a new iteration of the form if the end user exits forward or branches to the end of the form. This looping condition is in effect until the end user presses the GM_EXIT key. IAF ensures that the reiteration of the form occurs only after normal end-of-form actions take place (i.e. the current transaction commits or rolls back). The /REPEAT form qualifier implicitly executes a START_TRANSACTION statement at the beginning of the form and a COMMIT statement at the end of the form. This causes a transaction to start and commit with each iteration of the form. All actions associated with the COMMIT statement (i.e. implicit CLEAR_BUFFER statement execution) occur unless a CONTINUE ROLLBACK statement executes in the form, or the COMMIT statement pairs with a pseudo START_TRANSACTION. For details regarding the START_TRANSACTION and CLEAR_BUFFER statements, refer to their description in this manuals LANGUAGE STATEMENTS chapter. For details regarding transactions, refer to the IAF Users Guide. You can manipulate the /REPEAT qualifiers looping effect via the EXIT and CONTINUE statements. For details regarding the EXIT and CONTINUE statements, refer to this manuals LANGUAGE STATEMENTS chapter. By default, IAF returns the screen to its original clean state (i.e. input and output areas are cleared) with each iteration of a NORMAL form that includes the /REPEAT qualifier. However, you can optionally include the NOCLEAN keyword with this qualifier to disable this default behavior.

Forms and Form Qualifiers IAF 8.0 DML

3-129

/RFOOTING

/RFOOTING
Syntax
/RFOOTING=expression

Description This qualifier allows you to specify a page footing that is to print at the bottom right of each page of a given report. A REPORT_FORM statement can include any number of /RFOOTING qualifiers, as well as /FOOTING and /LFOOTING qualifiers. IAF determines the complete page footings for a report by examining the /RFOOTING, /FOOTING, and /LFOOTING qualifier expressions in the order in which the REPORT_FORM statement includes them. IAF places the footings left to right across the bottom of the report page, unless a given footings justification requires it to print on a new line. For details regarding the /FOOTING and /LFOOTING qualifiers, refer to their descriptions in this chapter.

Example
REPORT_FORM MAIN /TABLE=SALES_ORDERS & /RFOOTING=My Company Name & /RFOOTING=Sales Orders Report & /FOOTING=(Page & %PAGE)

The page footings that this example generates appear as follows:

Figure 3-14: Report Page Footings

3-130

Forms and Form Qualifiers IAF 8.0 DML

/RHEADING

/RHEADING
Syntax
/RHEADING=expression

Description
This qualifier allows you to specify a page heading that is to print at the top right of each page of a given report. A REPORT_FORM statement can include any number of /RHEADING qualifiers, as well as /HEADING and /LHEADING qualifiers. IAF determines the complete page headings for a report by examining the /RHEADING, /HEADING, and /LHEADING qualifier expressions in the order in which the REPORT_FORM statement includes them. IAF places the headings left to right across the top of the report page, unless a given headings justification requires it to print on a new line. For details regarding the /HEADING and /LHEADING qualifiers, refer to their descriptions in this chapter.

iBrowser Note
/RHEADING will display the complete heading text aligned to the right. If it is wider than the space between the beginning of the table and the right limit of the column, it will truncate. In case there is not enough space for the text it will omit the heading.

Example
REPORT_FORM MAIN /TABLE=SALES_ORDERS & /RHEADING=Orders Report & /RHEADING=My Company Name & /RHEADING=(Page & %PAGE)

The page headings that this example generates appear as follows:

Figure 3-15: Report Page Headings

Forms and Form Qualifiers IAF 8.0 DML

3-131

/ROW

/ROW
Syntax
/ROW=numeric_expression

Description
This qualifier allows you to specify the screen row that is to be the first row of the current MENU, NORMAL, QUERY, or TABLE_EDIT forms window, and is mandatory for these form types.

Examples
/ROW=3 /ROW=#NEW_ROW /ROW=(#MAX_ROWS/2)

3-132

Forms and Form Qualifiers IAF 8.0 DML

/ROW_HEIGHT

/ROW_HEIGHT
Syntax
/ROW_HEIGHT=numeric_value

Description
This qualifier allows you to specify the number of screen display lines that a TABLE_EDIT form is to allot for each record in the selected set. By default, IAF allots one screen row for each record in the selected set. If you specify a row height greater than one, the cursor moves up or down the specified number of lines each time the end user presses the GM_UP or GM_DOWN key, respectively.

Example
/ROW_HEIGHT=2

Forms and Form Qualifiers IAF 8.0 DML

3-133

/SECONDARY

/SECONDARY
Syntax
/SECONDARY

Description
This qualifier indicates that IAF is to create a secondary stream to enable the end user to examine and modify records without overwriting the contents of the user buffer associated with the given tables primary stream. Secondary streams do not permit record additions or deletions. Multiple secondary streams can exist per table. To access the records that a secondary stream retrieves, explicitly reference the secondary stream by its stream name. A secondary stream that IAF creates as a result of the /SECONDARY form qualifier has the same name as the given form. For details regarding secondary streams, refer to the IAF Users Guide.

Example
PROCEDURE_FORM CALC_TOTAL & /TABLE=CUSTOMERS & /SECONDARY BEGIN_BLOCK GRAND_TOTAL #TOTAL=#TOTAL+CALC_TOTAL:CUSTOMERS(BALANCE) END_BLOCK END_FORM

This form calculates the total balance on the CUSTOMERS table without destroying the current customer record.

3-134

Forms and Form Qualifiers IAF 8.0 DML

/SELECTION

/SELECTION
Syntax
/SELECTION=boolean_expression

or
/SELECTION=keyword

Description
This qualifier allows you to specify a Boolean selection statement indicating the record selection criteria IAF is to use. A Boolean selection statement is a logical combination of some or all /WITH clauses that the given form specifies. IAF assigns each clause an identifier of A-Z, where A represents the first /WITH clause, B represents the second /WITH clause, and so on. A Boolean selection statement can use these identifiers to refer to /WITH clauses. Alternatively, a Boolean selection statement can use identifiers consisting of an asterisk (*) followed by a number, where *1 represents the first /WITH clause, *2 represents the second /WITH clause, and so on. The advantage of using identifiers of the latter type is that they make it is possible to refer to more than 26 /WITH clauses (i.e. the limit that the alphabet imposes). A Boolean selection statement can use identifiers of all one type or a combination of both types, and may refer to a given /WITH clause once, more than once, or not at all.

Operator Precedence
The table on the following page lists in order of precedence the Boolean operators that are available for use with the /SELECTION qualifier. Note that by using parentheses it is possible to change the order in which IAF evaluates a given selection statement. Operator NOT Example A OR NOT B Selection Behavior This example specifies that /WITH clause A must be true or /WITH clause B must be false for a given record selection to take place.

Forms and Form Qualifiers IAF 8.0 DML

3-135

/SELECTION

Operator

Example A AND NOT B

Selection Behavior This example specifies that /WITH clause A must be true and /WITH clause B must be false for a given record selection to take place. This example specifies that /WITH clauses A and B must be true for a given record selection to take place. This example specifies that /WITH clause A or /WITH clause B must be true for a given record selection to take place.

AND

A AND B

OR

A OR B

In place of a Boolean selection statement, the /SELECTION qualifier can specify one of the keywords that the following table lists. Keyword ALL Selection Behavior This keyword specifies that all /WITH clauses must be true for a given record selection to take place. This is the default behavior if no /SELECTION qualifier is present. This keyword specifies that at least one /WITH clause must be true for a given record selection to take place.

ANY

Examples
If you specify the following /WITH clauses:
/WITH=CUSTOMER_ID=10506 /WITH=CUSTOMER_ID=10507 /WITH=ORDER_DATE=19-DEC-1993 /WITH=REQUIRED_DATE=%TODAY

The following /SELECTION qualifier would be valid:

/SELECTION=(A OR B) AND C AND NOT D

This /SELECTION qualifier causes the form to select the records for orders dated 19-DEC-1993 placed by customers who have the ID 10506 or 10507 who require their order before today.

3-136

Forms and Form Qualifiers IAF 8.0 DML

/SELECTION

The following /SELECTION qualifier would also be valid:

/SELECTION=ANY

This /SELECTION qualifier causes the form to select the records for orders dated 19-DEC-1993, or orders placed by customers who have the ID 10506 or 10507, or orders for customers who require their order today.

Forms and Form Qualifiers IAF 8.0 DML

3-137

/SEQUENCE

/SEQUENCE
Syntax
/SEQUENCE=field_name

Description
This qualifier allows you to specify a numeric field that is to hold stream sequence numbers for the records that a TABLE_EDIT form selects. IAF uses the sequence number field to distinguish detail records that pertain to a given master record. IAF writes a sequence number to the field for each record that an end user inserts into the detail table via the TABLE_EDIT form. The field that the /SEQUENCE qualifier specifies must reside in the first table that the /TABLE qualifier specifies and should be one of the fields that comprise the detail tables primary identifier (PID) and the only varying field in the PID. The other field(s) that comprise the detail tables PID should also be numeric and should comprise the master tables PID. A given TABLE_FORM statement can specify only one /SEQUENCE qualifier. Specifying a /SEQUENCE qualifier causes the given TABLE_EDIT form to behave as follows: Upon inserting a new record to the TABLE_EDIT form, IAF automatically generates a sequence value (i.e. 1, 2, 3, etc.) and writes it to the records sequence field. IAF does not alter sequence values of existing records in the TABLE_EDIT form. Therefore, IAF allows record insertions to take place only at the end of the forms list of records, unless a sequence number is available earlier in the sequence as a result of a record deletion. When IAF deletes a record from the TABLE_EDIT form, the records sequence number becomes available again. To cause a new record to have the sequence number of a previously deleted record, the end user must move the cursor to the record having the next highest sequence number (relative to the deleted records sequence number) prior to pressing the GM_INSERT_ROW key to insert the new record. If the cursor is at the end of the TABLE_EDIT forms list of records when the end user presses the GM_INSERT_ROW

3-138

Forms and Form Qualifiers IAF 8.0 DML

/SEQUENCE

key, IAF inserts the record using the next available number at the end of the sequence, and does not use any earlier sequence numbers that are available.

Example
Assume that the following fields comprise the ORDER_LINES detail tables PID:
ORDER_NUMBER LINE_NUMBER

where the LINE_NUMBER field distinguishes order detail lines having the same ORDER_NUMBER value. Also assume that the ORDER_NUMBER field is the sole PID field for the SALES_ORDERS table which is the master table. An appropriate /SEQUENCE qualifier would be as follow:
TABLE_FORM LINES & /TABLE=ORDER_LINES & /JOINED_TO=SALES_ORDERS & /SEQUENCE=LINE_NUMBER

Forms and Form Qualifiers IAF 8.0 DML

3-139

/SEQUENCE_INCREMENT

/SEQUENCE_INCREMENT
Syntax
/SEQUENCE_INCREMENT=numeric_expression

Description
This qualifier allows you to change the default sequence increment that IAF uses when assigning stream sequence numbers to records that an end user inserts into a table via a TABLE_EDIT form whose header statement includes the /SEQUENCE qualifier. The /SEQUENCE_INCREMENT qualifier is valid for use with any TABLE_FORM statement that includes the /SEQUENCE qualifier. By default, IAF uses a default sequence increment of one. The numeric expression applies only to the sequence number that IAF writes to a record inserted at the end of a TABLE_EDIT forms list of records. For details on sequence numbers, refer to this chapters description of the /SEQUENCE qualifier.

Example
/SEQUENCE_INCREMENT=10

3-140

Forms and Form Qualifiers IAF 8.0 DML

/SORTED_BY

/SORTED_BY
Syntax
/SORTED_BY=([-]field_name[,...])

or
/SORTED_BY=([-]table_name(field_name)[,...])

or
/SORTED_BY=([-]context.field_name[,...])

or
/SORTED_BY=([-]#variable_name[,...])

Description
This qualifier allows you to specify the order in which IAF is to sort selected records. If you specify multiple sort fields via one or more /SORTED_BY qualifiers, specify them in descending significance order (e.g. sort by state then city, instead of city then state). If a specified field resides in a table other than the first of multiple tables that the /TABLE qualifier specifies, you must prefix the fields name by the name of the table in which the field resides. The default sort order is ascending. To specify a descending sort order for a field, prefix its name by a minus sign (-). If the /TABLE qualifier specifies a given table name more than once, you must use a context variable to indicate which occurrence of the table to use. Likewise, if the /TABLE qualifier specifies a variable set to a table name, you must use a context variable to refer to the table. Context variables are letter designations that IAF assigns to tables that the /TABLE qualifier specifies. The first table that the /TABLE qualifier specifies is A, the second is B, and so on. A form header statement may include multiple /SORTED_BY qualifiers. Specifying multiple /SORTED_BY qualifiers is equivalent to specifying one /SORTED_BY qualifier with multiple sorted by clauses.

Forms and Form Qualifiers IAF 8.0 DML

3-141

/SORTED_BY

Examples
/SORTED_BY=(EMPLOYEE_ID)

This qualifier causes IAF to sort records by ascending employee ID.

/SORTED_BY=(DEPARTMENT,EMPLOYEES(EMPLOYEE_ID))

This qualifier causes IAF to sort records by ascending employee ID within ascending department number.
/TABLE=REGIONS,CUSTOMERS & /SORTED_BY=(#REG,#CUST_ID)

Assuming that the #REG variable contains A.REGION, and the #CUST_ID variable contains B.CUSTOMER_ID, these qualifiers cause IAF to sort records by ascending customer ID within ascending region number.
/SORTED_BY=(REGION,CUSTOMER_ID,-ORDER_NUMBER)

This qualifier causes IAF to sort records by descending order number within ascending customer ID within ascending region number.
/TABLE=STRUCTURES,PARTS,PARTS & /SORTED_BY=(B.PART_CODE,C.PART_CODE)

These qualifiers cause IAF to sort records by ascending sub-part code within ascending master part code. Note the use of context variables.

3-142

Forms and Form Qualifiers IAF 8.0 DML

/STATISTIC

/STATISTIC
Syntax
/STATISTIC=variable=statistic_function

Description
This qualifier allows you to gather statistical data about records, and is intended for use with the /GROUPED_BY qualifier. Using the /STATISTIC qualifier with the /GROUPED_BY qualifier causes IAF to perform the given statistic function for each group of records. Using the /STATISTIC qualifier without the /GROUPED_BY qualifier causes IAF to perform the given function for each record in the set. Either way, IAF places the functions result in the given variable. A form may include multiple /STATISTIC qualifiers. For details on the /GROUPED_BY qualifier, refer to its description in this chapter. The following table lists and describes the statistic functions that are valid for use with the /STATISTIC qualifier. Statistic Function AVERAGE(table_name(field_name)) Description This function returns the given fields average value for the given group of records. This function counts the records in the given group. This function returns the given fields maximum value for the given group of records.

COUNT

MAX(table_name(field_name))

Forms and Form Qualifiers IAF 8.0 DML

3-143

/STATISTIC

Statistic Function MIN(table_name(field_name))

Description This function returns the given fields minimum value for the given group of records. This function returns the given fields sample standard deviation by taking the square root of the following formulas result, where n is the count of the values used, and x is the table fields value:
x ) -- n -------------------------------------n1

SAMPLE_STD_DEV(table_name(field_name))

(x

STD_DEV(table_name(field_name))

This function returns the given fields population standard deviation by taking the square root of the following formulas result, where n is the count of the values used, and x is the table fields value:
x ) -- n -------------------------------------n

(x

3-144

Forms and Form Qualifiers IAF 8.0 DML

/STATISTIC

Statistic Function TOTAL(table_name(field_name))

Description This function returns the given fields total value for the given group of records.

The AVERAGE, SAMPLE_STD_DEV, STD_DEV, and TOTAL statistic functions accumulate only numeric data (data from fields having numeric native datatypes, or from text fields whose contents are convertible to a numeric value). These functions return a zero value for any other field type. The MIN and MAX functions use the fields native datatype when comparing data. These functions evaluate a text field as text regardless of whether or not its contents are convertible to a numeric value. Except for the COUNT function, statistic functions do not process missing values. Therefore, it is possible for the AVERAGE function to print a value that does not equal the fields total value for the group divided by the number of records in the group. For details on missing values, refer to the IAF Users Guide.

Examples
The following PROCEDURE form calculates the average age of employees.
PROCEDURE_FORM MAIN PERFORM AVG_AGE OUTPUT_BLOCK /ROW=1 /COL=1 & /PROMPT=Average Age & /SOURCE=#AVERAGE AGE & /OUTPUT_MASK=!-@@@ END_FORM PROCEDURE_FORM AVG_AGE & /TABLE=EMPLOYEES & /STATISTIC=#AVERAGE_AGE=AVERAGE(EMPLOYEES(AGE)) END_FORM

Forms and Form Qualifiers IAF 8.0 DML

3-145

/STATISTIC

The following example reports on the number of employees in each department and the total of all employee salaries for each department. The report produces one output line for each department.
REPORT_FORM MAIN & /OUTPUT=A.LIS & /WIDTH=80 & /HEADING=Departmental Statistics & /TABLE=EMPLOYEES & /SORTED_BY=DEPARTMENT & /GROUPED_BY=DEPARTMENT & /STATISTIC=#DEPARTMENT_COUNT=COUNT & /STATISTIC=#TOTAL_SALARY=TOTAL(EMPLOYEES(SALARY)) OUTPUT_BLOCK DEPARTMENT /SOURCE=EMPLOYEES(DEPARTMENT) OUTPUT_BLOCK COUNT /SOURCE=#DEPARTMENT_COUNT OUTPUT_BLOCK SALARY & /SOURCE=#TOTAL_SALARY & /USING=EMPLOYEES(SALARY) END_FORM

3-146

Forms and Form Qualifiers IAF 8.0 DML

/STATUS

/STATUS
Syntax
/STATUS

Description
This qualifier is applicable to REPORT and PROCEDURE forms. It indicates that IAF is to display a status window if the given forms processing phase exceeds 20 seconds. The processing phase includes any functions that IAF performs on the record set based upon the qualifiers that the form specifies (e.g. sorting, grouping, etc.). IAF updates the status window every 20 seconds for the duration of the processing phase. The status window does not appear during the forms record selection phase, regardless of the duration of the selection phase. REPORT forms have an implied /STATUS qualifier (i.e. the status window appears automatically if the processing phase exceeds 20 seconds). A REPORT_FORM statement can include the /NOSTATUS qualifier to override this default behavior. For details on the /NOSTATUS qualifier, refer to its description in this chapter. The following table lists and describes the status windows components. Component Status Description The Status component displays the number of the record that the form is currently processing, relative to the total number of records in the set, followed by a value indicating the number of records that the form is processing per second. Example: Elapsed On 1641 of 3204 85

The Elapsed component displays a value indicating the amount of time that has elapsed since the forms processing phase began. Example: 00:00:20.56

CPU

The CPU component displays a value indicating the amount of CPU time that the form has consumed since the forms processing phase began. Example: 00:00:16.08

Forms and Form Qualifiers IAF 8.0 DML

3-147

/STATUS

Component EOJ

Description The EOJ component displays a value that is an estimation of the amount of time left until the form completes the processing phase. Example: 0 00:00:19

Upon completing the forms processing phase, IAF removes the status window.

3-148

Forms and Form Qualifiers IAF 8.0 DML

/STREAM_NAME

/STREAM_NAME
Syntax
/STREAM_NAME=stream_name

Description
This qualifier allows you to specify the stream name that IAF is to assign to the stream that the given form starts. By default, IAF uses its own conventions to derive the name of a given stream. In most cases, a forms stream name is the same as the forms name. However, you can use the /STREAM_NAME qualifier to shorten a lengthy form name to an equally descriptive stream name. For details regarding streams and stream naming conventions, refer to the IAF Users Guide.

Example
PROCEDURE_FORM CALCULATE_ALL_BALANCES & /TABLE=CUSTOMERS & /STREAM_NAME=CALC /SECONDARY . . #TOTAL_BAL=#TOTAL_BAL+CALC:CUSTOMERS(BALANCE) . . END_FORM

Forms and Form Qualifiers IAF 8.0 DML

3-149

/SYSTEM

/SYSTEM
Syntax
/SYSTEM=[database_handle.]system

Description
This qualifier allows you to specify the default system that IAF is to use for ITEM blocks within a MENU form. Optionally, you may prefix the system name by a database handle. However, this is necessary only if you have invoked multiple databases, and the specified system does not exist in the current default database. The database handle must have been specified via the GEM_DATABASE_n SCV, INVOKE statement, or INVOKE option that invoked the database. The system that this qualifier specifies overrides the default system set via the SET SYSTEM statement. For details on systems, refer to the IAF System Reference Manual. For details on GEM_DATABASE_n and other SCVs, refer to the IAF guide that applies to your operating system. For details on the INVOKE and SET SYSTEM statements, refer to this manuals LANGUAGE STATEMENTS chapter. For details on the INVOKE option, refer to the IAF guide that applies to your database engine.

Examples
/SYSTEM=BILL_OF_MATERIALS /SYSTEM=FINANCE.FIXED_ASSETS

3-150

Forms and Form Qualifiers IAF 8.0 DML

/TABLE

/TABLE
Syntax
/TABLE=[database_handle.]table_name[,table_name[,...]]

or
/TABLE=#variable[,#variable[,...]]

Description
This qualifier allows you to specify the table(s) in which the records that the given form is to process reside. If the /TABLE qualifier includes more than one table name specification, IAF automatically determines the join key to use to join the tables, and then performs the join. Joining the tables that the /TABLE qualifier specifies allows IAF to retrieve records from the /TABLE qualifiers second and subsequent tables at the same time that it retrieves a related record from the /TABLE qualifiers first table. If a forms /TABLE qualifier specifies only one table, the form executes once for each of the tables records that meets the given selection criteria. If a forms /TABLE qualifier specifies multiple tables, the form executes for each of the joined sets records that meets the given selection criteria. Form execution completes when the form fetches the last record in the set, or the form exits via a non-normal exit status (the end user presses GM_EXIT at the first input.) Optionally, a database handle may precede the given table name(s). However, this is necessary only if you have invoked multiple databases, and the specified tables do not exist in the current default database. All tables that the /TABLE qualifier specifies must exist in the same database. The /TABLE qualifier can specify a table by specifying a variable that is set to the given tables name. Optionally, the first variable that the /TABLE qualifier specifies may prefix the given table name by a database handle. When the /TABLE qualifier specifies a variable that is set to a tables name, IAF imposes the following restrictions and conditions on the record selection process: Name checking and translation occurs at run-time, and therefore, may reduce form execution speed. When compiling the form via a COMPILE statement that includes the /CHECK qualifier, IAF does not check the forms record
Forms and Form Qualifiers IAF 8.0 DML 3-151

/TABLE

selection expressions. For details regarding the COMPILE statement, refer to its description in this manuals LANGUAGE STATEMENTS chapter. Qualifiers that specify a table name (e.g. /SORTED_BY, /REDUCED_TO, /WITH, etc.) must specify the table name via the appropriate context variable. IAF does not allow a record selection expression to include both a variable table name and an actual table name. The /TABLE qualifier is mandatory for TABLE_EDIT, QUERY, and REPORT forms and optional for NORMAL and PROCEDURE forms. Specifying /TABLE on a NORMAL or PROCEDURE form causes the form to execute as a loop (i.e. once per applicable record). The /TABLE qualifier does not apply to MENU forms. Because IAF automatically determines join keys between multiple tables that the /TABLE qualifier specifies, it is not necessary to use the /WITH qualifier to specify join keys. However, using context variables in /WITH qualifier specifications facilitates overriding the default joins that IAF sets up. For details on overriding default joins in this manner, refer to this chapters description of the /WITH qualifier. For more information regarding forms and the /TABLE qualifier, refer to the IAF Users Guide.

3-152

Forms and Form Qualifiers IAF 8.0 DML

/TABLE

Examples
FORM MAIN /TABLE=CUSTOMERS . . . END_FORM

This form executes for each CUSTOMERS table record.

PROCEDURE_FORM ORDERS /TABLE=CUSTOMERS,SALES_ORDERS . . . END_FORM

This form executes for each CUSTOMERS table record for which one or more related SALES_ORDERS table records exist.
TABLE_FORM DEPTS /TABLE=CUSTOMERS,DEPARTMENTS,SALES_ORDERS . . . END_FORM

This form executes for each CUSTOMERS table record for which one or more related DEPARTMENTS table records and SALES_ORDERS table records exist.
REPORT_FORM ORDERS /TABLE=DIST.SALES_ORDERS,SALES_ORDER_LINES . . . END_FORM

This form executes for each SALES_ORDERS table record for which one or more related SALES_ORDER_LINES table records exist. The /TABLE qualifier indicates that both tables reside in the database that has the database handle DIST.

Forms and Form Qualifiers IAF 8.0 DML

3-153

/TAG_LENGTH

/TAG_LENGTH
Syntax
/TAG_LENGTH=numeric_expression

Description
This qualifier allows you to specify the default tag length for ITEM blocks on a MENU form. IAF truncates longer tags and extends shorter tags to the length that this qualifier specifies. To override the given tag length for a particular ITEM block, append the /TAG_LENGTH block qualifier to the given ITEM block. In the absence of a /TAG_LENGTH form or block qualifier, an ITEM blocks tag length equals the given tags size.

Examples
/TAG_LENGTH=8 /TAG_LENGTH=(#MAX_LEN/2)

3-154

Forms and Form Qualifiers IAF 8.0 DML

/TITLE

/TITLE
Syntax
/TITLE=expression

Description
This qualifier allows you to specify the form title IAF is to display when it executes the given form. IAF displays the forms title at the top center of the forms window border. IAF truncates any form title that is longer than the width of the form for which the title is defined. This qualifier is intended primarily for use with MENU, NORMAL, QUERY, and TABLE_EDIT forms, although you can also use it with REPORT and PROCEDURE forms. For a REPORT or PROCEDURE form, the given title appears only as a line of DML code when editing the form via the Forms Editor, and does not display when the form executes.

Example
/TITLE=(Query of Common Records) /TITLE=(Orders for Customer & CUSTOMERS(CUSTOMER_ID)) /TITLE=#NEW_TITLE

Forms and Form Qualifiers IAF 8.0 DML

3-155

/WIDTH

/WIDTH
Syntax
/WIDTH=numeric_expression

Description
This qualifier applies to NORMAL, TABLE_EDIT, QUERY, MENU, and REPORT forms.
For NORMAL, TABLE_EDIT, QUERY, and MENU forms:

This qualifier is mandatory for these form types and allows you to specify the width of a given forms display window.
For REPORT forms:

This qualifier is optional for REPORT forms and allows you to specify the given REPORT forms print/display width. If a REPORT_FORM statement does not include this qualifier, IAF uses a default width of 132 columns.

Examples
/WIDTH=78 /WIDTH=#NEW_WIDTH /WIDTH=(#MAX_WIDTHS/2)

3-156

Forms and Form Qualifiers IAF 8.0 DML

/WITH

/WITH
Syntax
/WITH=field_name operator expression

or
/WITH=table_name(field_name) operator expression

or
/WITH=context.field_name operator expression

or
/WITH=[context.]field_name=[context.]field_name

Description
This qualifier allows you to specify clauses to qualify the specified tables records and thereby create subsets of the tables records. Any form header statement that includes one or more /WITH qualifiers must also include the /TABLE qualifier. IAF imposes no limit to the number of /WITH qualifiers a single form header statement may include. Following are descriptions of the components that comprise a /WITH qualifiers specification:
table_name

This is the name of the table in which the given field resides. If no table name or context variable is present, IAF assumes that the field resides in the first table that the /TABLE form qualifier specifies. If the /TABLE qualifier specifies multiple tables, or specifies the same table name more than once, the /WITH qualifier can use a context variable (see below) to uniquely identify the desired table.
context

This is a context variable indicating the table in which the given field resides. If the /TABLE form qualifier specifies multiple tables, or specifies the same table name more than once, the /WITH qualifier can use a context variable to uniquely identify the desired table. Context variables are letter designations, A-Z, that IAF assigns to the table(s) that the /TABLE qualifier specifies. The first table that the /TABLE qualifier specifies is A, the second table is B, and so on. If no table

Forms and Form Qualifiers IAF 8.0 DML

3-157

/WITH

name or context variable is present, IAF assumes that the field resides in the first table that the /TABLE qualifier specifies.
field_name

This is the name of the field whose data IAF is to examine as part of the given forms record selection process. If the field resides in a table other than the first table that the /TABLE qualifier specifies, the /WITH qualifier must prefix the field name by the name of the table in which the field resides.
operator

This is an indicator of the mathematical, logical, or textual operation that IAF is to perform on the given data. The table on the following page lists and describes the relational operators that are valid for use with a /WITH qualifier. Note that you can prefix the last five operators in the table by the NOT operator to reverse their effect. Operator = <> <= Description Determines if the value of the field on its left is equal to the value of the expression on its right. Determines if the value of the field on its left is unequal to the value of the expression on its right. Determines if the value of the field on its left is less than or equal to the value of the expression on its right. Determines if the value of the field on its left is greater than or equal to the value of the expression on its right. Determines if the value of the field on its left is less than the value of the expression on its right. Determines if the value of the field on its left is greater than the value of the expression on its right. Determines if the data in the field on its left starts with the value of the expression on its right. This operator is a wildcard operator. Therefore, certain database engines may not support its use on nontext fields. To determine if a particular engine supports using this operator on non- text fields, refer to the IAF guide that applies to that database engine. This operator is case- sensitive.

>=

< > STARTING WITH

3-158

Forms and Form Qualifiers IAF 8.0 DML

/WITH

Operator MATCHING

Description Determines if the data in the field on its left matches the wildcard pattern on its right. This operator is a wildcard operator. Therefore, certain database engines may not support its use on non- text fields. To determine if a particular engine supports using this operator on non-text fields, refer to the IAF guide that applies to that database engine. This operator is not case-sensitive. Determines if the field on its left contains the data on its right. This operator is case-insensitive. Determines if the data in the field on its left is among the list of values and/or ranges on its right. This operator is a wildcard operator. Therefore, certain database engines may not support its use on non-text fields. To determine if a particular engine supports using this operator on non-text fields, refer to the IAF guide that applies to that database engine. Determines if the value in the field on its left is the missing value. This operator does not require an operand on its right. For details regarding missing values, refer to the IAF Users Guide. To determine if a particular database engine supports missing values, refer to the IAF guide that applies to that database engine.

CONTAINING AMONG

MISSING

expression
This is any valid DML expression, such as a literal, table field, or argument. Note: When any /WITH qualifier involving text comparisons is evaluated, the action is restricted to the length of the field defined on the left of the qualifier. Excess characters in the field or expression on the right of the qualifier are ignored. For example, consider a field, STATE, defined with a datatype of TEXT and a length of 2. Selections involving the qualifier /WITH = STATE = CAA succeed if this field on any record in the table contains CA. The excess character in the expression on the right of the qualifier is ignored.

Forms and Form Qualifiers IAF 8.0 DML

3-159

/WITH

Overriding Default Table Joins

The /WITH qualifier facilitates overriding implicit and explicit table joins by enabling you to specify your own join fields for the given tables via context variables. The recommended procedure is to prefix the expression to the left of the /WITH clauses operator and the expression to the right of the /WITH clauses operator by a context variable. It is necessary to prefix the expression to the right of the operator by a context variable to override any implicit and/or explicit table joins. Prefixing the expression to the left of the operator by a context variable is optional. The first example on the following page uses context variables to override any implicit and/or explicit table joins that IAF would otherwise perform and causes IAF to select records based upon the specified join fields.

/TABLE=ORDERS,ORDER_LINES & /WITH=B.BACK_ORDER_NUMBER = A.ORDER_NUMBER

This example assumes that when an order is filled, any order lines that reference items that are not available are assigned a backorder number. Therefore, each order line can be associated with two order numbers (i.e. an original order number and a backorder number). By default, IAF would implicitly join the ORDERS and ORDER_LINES tables via the ORDER_NUMBER field which they both contain. However, this examples use of context variables causes IAF to join a given ORDERS table record and a given ORDER_LINES table record only if the ORDERS records ORDER_NUMBER field and the ORDER_LINES records BACK_ORDER_NUMBER field hold the same value. The following example, which assumes the same scenario as the preceding example and is similar in appearance, performs a completely different function due to the absence of context variables:
/TABLE=ORDERS,ORDER_LINES & /WITH=ORDER_LINES(BACK_ORDER_NUMBER) = ORDERS(ORDER_NUMBER)

This example causes IAF to implicitly join ORDERS table records and ORDER_LINES table records via the ORDER_NUMBER field which they both contain. This means that IAF joins a given ORDERS table record and a given ORDER_LINES table record only if the ORDER_NUMBER fields value is the same for both records. Additionally, this examples /WITH clause causes IAF to produce a subset of joined records that consists of those ORDER_LINES records whose BACK_ORDER_NUMBER field has the same value as the ORDER_NUMBER field in the current ORDERS table record (i.e. the ORDERS record that is currently in memory).
3-160 Forms and Form Qualifiers IAF 8.0 DML

/WITH

NOTE:
A /WITH qualifier that defines an explicit join via context variables causes IAF to ignore all default joins between the tables that the forms /TABLE qualifier specifies. Therefore, it is necessary to explicitly define all joins between tables that a forms /TABLE qualifier specifies if the form header statement includes any /WITH qualifiers that uses context variables.

Comparing Fields within a Table

/WITH qualifiers can also use context variables to perform comparisons on fields that reside within the same table to determine whether a given relationship exists between the fields. To cause IAF to interpret a given /WITH clause as a comparison between two fields, use the following format for the expression component of the clause:
context.field_name

When specifying a /WITH clause that uses a context variable with a field name to the right of the operator, it is also advisable to use a context variable with the field name to the left of the operator. The following example illustrates this use of context variables, and causes IAF to produce a subset of CUSTOMERS table records in which each records BALANCE field value exceeds its CREDIT_LIMIT field value:
/TABLE=CUSTOMERS & /WITH=A.BALANCE > A.CREDIT_LIMIT

The following example, while similar in appearance, performs a completely different function due to the absence of context variables:
/TABLE=CUSTOMERS & /WITH=CUSTOMERS(BALANCE)>CUSTOMERS(CREDIT_LIMIT)

This example causes IAF to produce a subset of records in which each records BALANCE field value exceeds the CREDIT_LIMIT field value in the current CUSTOMERS table record (i.e. the record currently in memory).

Forms and Form Qualifiers IAF 8.0 DML

3-161

/WITH

NOTE:
Using context variables in a /WITH clause overrides the default table joins that IAF would normally perform between the tables that the /TABLE qualifier specifies. Therefore, it is necessary to explicitly define all joins between tables that a forms /TABLE qualifier specifies if the form header statement includes a /WITH qualifier that uses context variables.

Missing Values
A fields value is either missing or not missing. If data has been explicitly assigned to a given field, that fields value is not missing. Otherwise, its value is missing. A /WITH qualifier that references a field that contains explicitly assigned data (i.e. its value is not missing) produces predictable, consistent results. However, a /WITH qualifier that references a field to which no data has been explicitly assigned (i.e. its value is missing) may produce unexpected, undesired results. For example, suppose a given table contains records for which no data has been explicitly assigned to the STATUS field (i.e. its value is missing). The following /WITH qualifier causes IAF to create a subset of records that contains records for which the STATUS fields value does not equal A (i.e. the subset does not include records having a STATUS field value of A or a STATUS field value that is missing):
/WITH=STATUS<>A

The subset that this /WITH qualifier produces is not a true reflection of the intended operation (it does not produce a subset containing all records having a STATUS field value other than A). If a /WITH qualifier checks a fields value for equality with the value that is defined as the missing value for that field, the resultant record subset will be empty. For example, if the missing value for the STATUS field is defined as B, the following /WITH qualifier produces an empty record subset:
/WITH=STATUS=B

Explicitly assigning a fields designated missing value to the field causes IAF to recognize the fields value as missing.

3-162

Forms and Form Qualifiers IAF 8.0 DML

/WITH

The table on the following page lists and describes the effects of the two variations of the MISSING operator. MISSING Determines if the given fields value is missing (i.e. no data other than the missing value has been assigned to it). Example:/WITH=STATUS MISSING Determines if data other than the missing value has been explicitly assigned to the field. Example:/WITH=STATUS NOT MISSING

NOT MISSING

For a more detailed discussion of missing values, refer to the IAF Users Guide.

NOTE:
Not all database engines support missing values. To determine if a particular database engine supports missing values, refer to the IAF guide that applies to that database engine.

Wildcard Character Matching

Expressions in /WITH clauses that use MATCHING or AMONG operators may include wildcard characters. There are two wildcard characters that are valid for use in these expressions. These are the asterisk (*) and percent sign (%) characters, where * replaces zero or more unknown characters, and % replaces a single unknown character. A single expression may make use of one or both of these characters. Trailing spaces on data in fixed length text fields are significant when performing wildcard operations. Therefore, a wildcard expression should include a trailing * if the expression accounts for less than the number of characters that a given field holds. For example, given a 10 character field, a wildcard pattern of ac* matches both acid and acidic, while a wildcard pattern of ac%% matches neither value because it does not take the trailing spaces into account. A wildcard pattern of ac%% * matches acid. The following /WITH qualifier produces a record subset that contains records for which the MOVIE_TITLE field begins with the letter S:
/WITH=MOVIE_TITLE MATCHING S*

The following /WITH qualifier produces a record subset that contains records for which the MOVIE_TITLE field contains XA preceded and followed by zero or more unknown characters:
/WITH=MOVIE_TITLE MATCHING *XA*

Forms and Form Qualifiers IAF 8.0 DML

3-163

/WITH

The following /WITH qualifier produces a record subset that contains records for which the MOVIE_TITLE fields value is S followed by three unknown characters:
/WITH=MOVIE_TITLE MATCHING S%%%

The following /WITH qualifier produces a record subset that contains records for which the MOVIE_TITLE field contains any number of unknown characters. The subset includes any records for which the MOVIE_TITLE fields value is missing.
/WITH=MOVIE_TITLE MATCHING *

NOTE:
Some database engines do not allow wildcard operations to be performed on non-text fields. To determine if this restriction applies to a particular database engine, refer to the IAF guide that applies to that database engine.

Examples
/WITH=ORDER_DATE < 15-AUG-1995

This qualifier produces a record subset that contains records from the first table that the /TABLE qualifier specifies for which the ORDER_DATE field contains a date prior to 15-AUG-95.
/WITH=TOTAL_VALUE > 20000.00

This qualifier produces a record subset that contains records from the first table that the /TABLE qualifier specifies for which the TOTAL_VALUE fields value is greater than 20,000.
/WITH=ORDERS(PART_CODE) = PARTS(PART_CODE)

This qualifier produces a record subset that contains ORDERS table records for which the PART_CODE field holds the same value as the PART_CODE field of the PARTS record that is currently in memory.
/WITH=SITE_ID = (#AREA&-0001)

This qualifier produces a record subset that contains records from the first table that the /TABLE qualifier specifies for which the SITE_ID field contains the value -0001 preceded by the value that the #AREA variable contains.
/WITH=CUSTOMER_ID STARTING WITH 10

3-164

Forms and Form Qualifiers IAF 8.0 DML

/WITH

This qualifier produces a record subset that contains records from the first table that the /TABLE qualifier specifies for which the CUSTOMER_ID fields value begins with 10.
/WITH=DEPARTMENT AMONG 101,213-218,31%,4%%

This qualifier produces a record subset that contains records from the first table that the /TABLE qualifier specifies for which the DEPARTMENT fields value is 101, 213 through 218, 310 through 319, or 400 through 499.
/WITH=START_DATE MISSING

This qualifier produces a record subset that contains records from the first table that the /TABLE qualifier specifies for which the START_DATE fields value is missing.

Forms and Form Qualifiers IAF 8.0 DML

3-165

/WITH

Streams with a /WITH Qualifier

For streams with a /WITH qualifier, the values of the fields in a stream are not preserved for an add.

Example 1:
PROCEDURE_FORM A FIND IN TEST_USER /WITH=TEST_USER_ID=S0001 TEST_USER (TEST_USE)= NAME ADD TO TEST_USER COMMIT END_FORM

1. 2. 3.

Prior to the FIND IN, no fields in the user buffer has been written to. After the FINE IN, still no fields in the user buffer are considered by IAF to have been written to. This is not an error. The TEST_USER (TEST_USER_NAME) field in the user buffer is written to. The TEST_USER (TEST_USER_ID) field in the user buffer is not written to. The row is added. Because the TEST_USER(TEST_USER_ID) field in the user buffer was never written to, the underlying database engine supplies the initial value for the field. For example; if the inital value for the TEST_USER (TEST_USER_ID) field is the literal value XXXX, then the field is added with XXXX in that field. The COMMIT statement commits the added row.

4.

5.

Example 2:
If you modify the program such as: The table/field TEST_USER (TEST_USER_ID) has a unique index.
PROCEDURE_FORM A FIND IN TEST_USER /WITH=TEST_USER_ID=S0001 ADD TO TEST_USER COMMIT END_FORM

1.

Prior to the FIND IN, no fields in the user buffer have been written to.

3-166

Forms and Form Qualifiers IAF 8.0 DML

/WITH

2. 3. 4.

After the FIND IN, still no fields in the user buffer are considered by IAF to have been written to. This is a FIND IN feature. No fields in the user buffer are written to. Because no fields in the user buffer were written to, the ADD TO statement is ignored and now row is added. (This is another IAF feature.) The COMMIT statement has nothing to commit.

5.

This example demonstrates that the FIND IN statement does not cause any of the fields in the buffer to be considered to have been written to. You can tell this is so because the IAF feature which causes the ADD TO statement to be ignored when no fields have been written to occurs and no row is added.

Example 3:
Again, modify the program as: The table/field TEST_USER (TEST_USER_ID) has a unique index.
PROCEDURE_FORM A FIND IN TEST_USER /WITH=TEST_USER_ID=S0001 TEST_USER (TEST_USER_ID)=TEST_USER (TEST_USER_ID) TEST_USER (TEST_USER_NAME)=NAME ADD TO TEST_USER COMMIT END_FORM

1. 2.

Prior to the FIND IN, no fields in the user buffer have been written to. After the FIND IN, still no fields in the user buffer are considered by IAF to have been written to. This is IAFs FIND IN statement feature. The TEST_USER (TEST_USER_ID) field in the user bufferwas written to, the database engine does not supply the initial value for the field. The user buffer supplies the value for the field. You receive a duplicate record error from the ADD TO. The COMMIT has nothing to commit.

3.

4.

Forms and Form Qualifiers IAF 8.0 DML

3-167

Chapter 4

Fixed Display Declarations

Fixed display declarations describe text and/or lines that IAF is to display on screen when initially executing the form that contains the declarations. During subsequent iterations of the form, IAF ignores the declarations. Fixed display declarations are unconditional. Therefore, placing them within a conditional construct, such as an IF or WHILE construct, has no effect. IAF displays the given text and/or lines regardless of whether the condition for which the construct tests exists. For details regarding IF and WHILE constructs, refer to the descriptions of the IF and WHILE statements in this manuals LANGUAGE STATEMENTS chapter. The remainder of this chapter provides details regarding the TEXT and LINE fixed display declarations.

4-2

Fixed Display Declarations IAF 8.0 DML

TEXT Declarations

TEXT Declarations
Any number of TEXT declarations can precede a NORMAL or TABLE_EDIT forms first block. IAF displays the given text during the forms initial set-up phase. To display text during the forms run-time phase instead of its set-up phase, use one of the following methods: Place the TEXT declaration in a PROCEDURE form, and call the PROCEDURE form from the given NORMAL or TABLE_EDIT form. Use an OUTPUT block with a /ATTRIBUTES=NONE qualifier. Note that inserting a special text formatting token at the beginning of a TEXT declarations text string, causes IAF to display the text in the given format.

Syntax
TEXT /ROW=numeric_expression /COL=numeric_expression [{token}]text

The components of this syntax are as follows:

text
This is the text that IAF displays on the screen.

token
This is one of the following mutually exclusive text formatting tokens: Token {H} Effect This token causes IAF to use high and wide characters when displaying the given text. The resulting characters occupy two screen rows. This token causes IAF to use wide characters when displaying the given text.

{W}

Fixed Display Declarations IAF 8.0 DML

4-3

TEXT Declarations

NOTE:
Most terminals do not allow mixed formats on the same screen row. Therefore, using a token may disturb any window borders that display on the same screen row as the given text. To remedy this situation, use the SET SCREEN NOBORDER statement in the given form to suppress the forms window border. For details regarding the SET SCREEN NOBORDER statement, refer to this chapter.

/ROW=numeric_expression
This mandatory qualifier allows you to indicate the window row on which to print the given text. The given numeric expression must be an integer greater than or equal to one and less than or equal to the forms height.

/COL=numeric_expression
This mandatory qualifier allows you to indicate the window column on which to begin printing the given text. The given numeric expression must be an integer greater than or equal to one and less than or equal to the forms width.

Examples:
TEXT /ROW=3 /COL=5 {H}SALES ORDER ENTRY TEXT /ROW=4 /COL=10 Total value is TEXT /ROW=#ENTRY_ROW /COL=#ENTRY_COLUMN Enter customer number:

This example assumes that the form that calls the form that contains the TEXT declaration set the #ENTRY_ROW and #ENTRY_COLUMN variables, or passed their values as arguments to the form that contains the TEXT declaration. For details on passing arguments, refer to the Introduction section in this manuals Forms And Form Qualifiers chapter.

4-4

Fixed Display Declarations IAF 8.0 DML

LINE Declarations

LINE Declarations
Any number of LINE declarations can precede a NORMAL, REPORT, or TABLE_EDIT forms first block. IAF displays the given line or box during the forms initial set-up phase. To display the line or box during the forms run-time phase instead of its set-up phase, place the LINE declaration in a PROCEDURE form, and call the PROCEDURE form from the given NORMAL, REPORT, or TABLE_EDIT form.

Syntax
LINE /ROW=numeric_expression /COL=numeric_expression /END_ROW=numeric_expression

or
LINE /ROW=numeric_expression /COL=numeric_expression /END_COL=numeric_expression

or
LINE /ROW=numeric_expression /COL=numeric_expression & /END_ROW=numeric_expression & /END_COL=numeric_expression

The components of this syntax are as follows:

numeric_expression
This is a valid DML expression whose value is a positive numeric integer that indicates a row or column. Indicateing a numeric expression whose value is a negative number or zero generates an error.

/ROW=numeric_expression
This qualifier allows you to indicate the window row on which to begin printing the line or box. The numeric expressions value must be an integer greater than or equal to one and less than or equal to the forms height. This qualifier is mandatory in LINE declarations.

/COL=numeric_expression
This qualifier allows you to indicate the window column in which to begin printing the line or box. The numeric expressions value must be an integer greater than or equal to one and less than or equal to the forms width. This qualifier is mandatory in LINE declarations.

Fixed Display Declarations IAF 8.0 DML

4-5

/END_ROW=numeric_expression
This qualifier allows you to indicate the window row on which to complete the line or box. The numeric expressions value must be an integer greater than or equal to the value that the /ROW qualifier specifies and less than or equal to the forms height. Specifying this qualifier without indicateing the /END_COL qualifier produces a vertical line. Specifying this qualifier with the /END_COL qualifier produces a box.

/END_COL=numeric_expression
This qualifier allows you to indicate the window column in which to complete the line or box. The numeric expressions value must be an integer greater than or equal to the value that the /COL qualifier specifies and less than or equal to the forms width. Specifying this qualifier without indicateing the /END_ROW qualifier produces a horizontal line. Specifying this qualifier with the /END_ROW qualifier produces a box.

Examples:
LINE /ROW=5 /COL=1 /END_COL=78 LINE /ROW=5 /COL=5 /END_ROW=15 LINE /ROW=#ROW1 /COL=#COL1 /END_ROW=#ROW2 /END_COL=#COL2

This example assumes that the form that calls the form that contains the LINE declaration set the #ROW1, #COL1, #ROW2, and #COL2 variables, or passed their values as arguments to the form that contains the LINE declaration. For details on passing arguments, refer to the Introduction section in this manuals Forms And Form Qualifiers chapter.

4-6

Fixed Display Declarations IAF 8.0 DML

Chapter 5

Blocks and Block Qualifiers

Blocks perform individual input, output, and processing functions within forms. The following table lists the block types that are available within IAFs DML and the block statements that define them, and indicates the purpose of each block type. Block Type DML Block Statement or Construct BEGIN_BLOCK and END_BLOCK INPUT ITEM MENU INPUT_BLOCK ITEM_BLOCK MENU_BLOCK Requests input data from the end user. Defines an option on a MENU form. Presents a menu of options to the end user. Outputs data to the screen or a disk file. Pauses and asks the end user to Press RETURN to continue.... Requests a single or double electronic signature form an end-user and validates that input. Prompts the end user to enter a response to a yes/no question. Purpose Performs general data manipulation.

OUTPUT PAUSE

OUTPUT_BLOCK PAUSE_BLOCK

SIGNATURE_BLOCK

SIGNATURE_BLOCK

YES/NO

YESNO_BLOCK

5-2

Blocks and Block Qualifiers IAF 8.0 DML

The remainder of this chapter has the following organization: The Introduction section contains information regarding the general specification and performance of block statements. A section for each block type (in alphabetical order by block type) describes the given block types typical use, and the block statement syntax and block qualifiers (for example; options) that are applicable to that block type. The Block Qualifiers section presents full descriptions of all block qualifiers available in the IAF DML. The section consists of a reference table that lists all block qualifiers alphabetically and indicates the block type(s) to which each block qualifier is applicable, and an alphabetized presentation of block qualifiers, including syntax, descriptions, and examples.

Blocks and Block Qualifiers IAF 8.0 DML

5-3

Introduction

Introduction
This section provides information regarding the general specification and performance of block statements.

Block Statement Syntax

Block statement syntax for all block types except DML blocks is as follows:
block_statement [block_name] [/qualifiers]

block_statement
This is the DML statement associated with the type of block you are defining. For details regarding a particular block statement, refer to this chapters section describing the block type that the statement defines.

block_name
This is the name of the block you are defining. If a block statement includes a block name, it must consist only of letters, numbers, and underscores, and must be no longer than 31 characters. The name must be unique within the form in which the block resides. A block name can serve as a label to which a DML program can branch via a GOTO statement. For details regarding the GOTO statement, refer to this manuals LANGUAGE STATEMENTS chapter.

/qualifiers
These are the qualifiers that indicate the options to activate for the given block. For information regarding the qualifiers that apply to a given block type, refer to this chapters section that pertains to that block type. For descriptions of all block qualifiers, refer to this chapters Block Qualifiers section. Unless otherwise noted, a given qualifier can be specified only once per block. If a qualifier allowing only one instance per block is specified more than once for a given block, IAF ignores all but the last instance of the qualifier.

5-4

Blocks and Block Qualifiers IAF 8.0 DML

BEGIN_BLOCK/END_BLOCK Construct

BEGIN_BLOCK/END_BLOCK Construct
A BEGIN_BLOCK/END_BLOCK construct must enclose a DML block, and optionally, may enclose blocks of other types. Following is the syntax for the construct:
BEGIN_BLOCK [/DISPLAY_ONLY] block_name [dml_code] [block_statement [block_name] [/qualifiers]] [dml_code] END_BLOCK

The BEGIN_BLOCK keyword marks the constructs beginning, and the END_BLOCK keyword marks the constructs end. Any amount of DML code can reside between these two keywords. If no INPUT_BLOCK, ITEM_BLOCK, MENU_BLOCK, OUTPUT_BLOCK, PAUSE_BLOCK, or YESNO_BLOCK statement is present, the construct defines a DML block. Otherwise, the construct defines a block of the given type and any attached DML code (for example; any DML statements in the construct.) A block name must immediately follow the BEGIN_BLOCK statement as the syntax above indicates. Any block statement within the construct may also indicate a block name. For more information regarding DML blocks, refer to this chapters DML Blocks section. IAF executes BEGIN_BLOCK/END_BLOCK constructs in the following order: IAF executes any attached DML code that precedes the block type statement (if one is present.) IAF executes the block type statement (if one is present.) IAF executes any attached DML code that follows the block type statement (if one is present.) Note that BEGIN_BLOCK/END_BLOCK constructs that include the /DISPLAY_ONLY qualifier cannot execute PERFORM or SWITCH statements, and cannot execute other blocks (for example; input or output blocks.) Following is an example of a BEGIN_BLOCK/END_BLOCK construct.

Blocks and Block Qualifiers IAF 8.0 DML

5-5

Completion Status

Example:
BEGIN_BLOCK INPUT_DISCOUNT #DEFAULT_DISCOUNT = #TOTAL_VALUE * 0.15 INPUT_BLOCK DISCOUNT /ROW=5 /COL=10 & /TARGET=SALES_ORDERS(DISCOUNT) & /SOURCE=#DEFAULT_DISCOUNT END_BLOCK

Completion Status
When IAF finishes executing a block, the block has a completion status. IAF places the completion status in the %STATUS special variable, which the given form can then examine. DML blocks are exceptions to this rule. A DML block has no completion status. Therefore, %STATUS retains the status value of the last DML operation that had an effect on %STATUS. Common completion status values are %EXIT and %BACK. %EXIT indicates that the end user pressed the GM_EXIT key at the block. %BACK indicates that the end user pressed the GM_BACK key at the block. For details regarding %STATUS, %EXIT, %BACK, and other special variables and value symbols, refer to this manuals Special Variables And Value Symbols chapter.

5-6

Blocks and Block Qualifiers IAF 8.0 DML

DML Blocks

DML Blocks
General Purpose
A DML block consists of one or more lines of DML code enclosed within a BEGIN_BLOCK/END_BLOCK construct. Typically, the DML code within the construct is cohesive. A DML block always has a name (preferably indicating the blocks function) and contains no other block type statements. It is advisable to always place DML code within blocks.

Block Statement Syntax

Following is the syntax for a DML block:
BEGIN_BLOCK [/DISPLAY_ONLY] block_name dml_code END_BLOCK

Implicit Block Actions

A DML block has no implicit function as do the other block types. The DML code within a DML block defines the blocks function.

Blocks and Block Qualifiers IAF 8.0 DML

5-7

DML Blocks

Special Considerations
DML blocks that include the /DISPLAY_ONLY qualifier cannot execute PERFORM or SWITCH statements.

Qualifiers
The /DISPLAY_ONLY qualifier is applicable to DML blocks. For details regarding the /DISPLAY_ONLY qualifier, refer to this chapters Block Qualifiers section.

Examples
BEGIN_BLOCK CALCULATE_CHARGE #DISCOUNT=#TOTAL_VALUE * 0.15 #CHARGE=#TOTAL_VALUE - #DISCOUNT SALES_ORDERS(CHARGE)=#CHARGE + #FREIGHT + #MISC_CHARGES END_BLOCK BEGIN_BLOCK CHECK_AGE_AND_DELETE #NO_ORDS=#NO_ORDS + 1 IF (DAYS(SALES_ORDERS(CLOSED_DATE)) < (DAYS(%TODAY)-60)) PERFORM DELETE_ORDER_LINES DELETE FROM SALES_ORDERS #NO_DEL=#NO_DEL + 1 END_IF END_BLOCK

5-8

Blocks and Block Qualifiers IAF 8.0 DML

INPUT Blocks

INPUT Blocks
General Purpose
An input block requests data from an end user and indicates the entity (variable or table field) in which IAF is to place the data. The various qualifiers available for use with input blocks facilitate validating the input data, Indicating a default value for the input, and performing a variety of other functions.

Block Statement Syntax

Following is the syntax for the INPUT_BLOCK statement, which is the block type statement to use for input blocks:
INPUT_BLOCK [block_name] & /ROW=numeric_expression & /COL=numeric_expression & /TARGET=data_element [/qualifiers]

Implicit Block Actions

If an input blocks target is a table field, IAF automatically performs any validation checks that the table fields definition indicates, such as datatype, valid value, and domain checks. IAF does not perform valid value or domain checks if the end user enters a null value for the input.

Special Considerations
If an input blocks target is a table field having a DOCUMENTARY native datatype, the input has a multiple-line input window to enable the end user to enter multiple lines of input data. Otherwise, the input has a single-line input window. When IAF first displays a multiple-line input window, only the first line of data displays, and the window looks like a single-line input window. Pressing the GM_SELECT_ROW key opens the window for multipleline editing. To exit the input area without opening the window for multiple-line editing, press the GM_CR or GM_FORWARD key. To exit a multiple-line editing window, press the GM_FORWARD or GM_EXIT_FORWARD key. Upon exiting the window, IAF displays only the first line of the fields data.

Blocks and Block Qualifiers IAF 8.0 DML

5-9

INPUT Blocks

Input blocks require the use of a screen window, and after an end user enters data for the input, the data remains in the window. However, a PROCEDURE form has no implicit screen window. Therefore, to execute an input block defined within a PROCEDURE form, IAF uses the first screen window belonging to a parent form of the PROCEDURE form. If an input block resides on the last line of a forms window, and the form calls a sub-form whose form header statement includes the /REMAIN qualifier, and an input error causes IAF to display an error message, IAF re-displays the calling form but not the called form. To avoid this problem, do not place an input block on the last three lines of a form that calls a form whose form header statement includes the /REMAIN qualifier.

Qualifiers
The following qualifiers are applicable to the INPUT_BLOCK statement. For details regarding these qualifiers, refer to this chapters Block Qualifiers section.
/ABSOLUTE_POSITION /ATTRIBUTES /BACK /COL /DISPLAY_LENGTH /DOMAIN /EXIT /EXIT_FORWARD /HEADING /HEIGHT /INPUT_MASK /LEN /LOV /LOV_AUTO_SELECT /LOV_COL /LOV_DATA /LOV_FIRST /LOV_HEIGHT /LOV_NOHEADING /LOV_NOSEARCH /LOV_REDUCED_TO /LOV_ROW /LOV_SECONDARY /LOV_SELECTION /LOV_SORTED_BY /LOV_WIDTH /LOV_WITH /NEW /NOCLEAR_BUFFER /NODOMAIN /NOLOV_DATA /NOUNDERLINES /OPTIONS /PROMPT /PROTECT /ROW /SOURCE /SOURCE_IF /TARGET /TITLE /USE_IF /USER_KEYn /USING

Example
INPUT_BLOCK GET_CUST_ID /ROW=10 /COL=20 & /PROMPT=FIELD_PROMPT(CUSTOMER_ID) & /TARGET=SALES_ORDERS(CUSTOMER_ID)

5-10

Blocks and Block Qualifiers IAF 8.0 DML

ITEM Blocks

ITEM Blocks
General Purpose
An item block defines the behavior and appearance of an option on a menu form. When an end user selects an item on a menu, IAF allows the facility that the item block specifies and performs the facilitys function.

Block Statement Syntax

Following is the syntax for the ITEM_BLOCK statement, which is the block type statement to use for item blocks:
ITEM_BLOCK [block_name] & /ROW=numeric_expression & /COL=numeric_expression & /FACILITY=[database_handle.][system:]facility [/qualifiers]

Implicit Block Actions

IAF displays an item blocks tag to facilitate selecting the item. If the item block does not indicate a tag via the /TAG qualifier, IAF uses the tag of the facility that the item blocks mandatory /FACILITY qualifier specifies. IAF also displays an item blocks description unless the block includes a null /SOURCE qualifier (/SOURCE=) to override this behavior. If the item block does not indicate a description via the /SOURCE qualifier, IAF uses the description of the facility that the item blocks mandatory /FACILITY qualifier specifies. The end user can move the cursor to a menu option by typing a portion of its tag or pressing the GM_UP or GM_DOWN key. The end user can then select the option by pressing the GM_SELECT_ROW or GM_CR key. IAF executes any DML code associated with the facility that the item blocks /FACILITY qualifier specifies.

Special Considerations
The /ROW and /COL qualifiers indicate the position in which the options tag is to display, and not the position in which the options description is to display.

Blocks and Block Qualifiers IAF 8.0 DML

5-11

ITEM Blocks

Qualifiers
The following qualifiers are applicable to the ITEM_BLOCK statement. For details regarding these qualifiers, refer to this chapters Block Qualifiers section.
/ATTRIBUTES /COL /FACILITY /PROMPT /ROW /SOURCE /TAG /TAG_LENGTH /USE_IF

Example
ITEM_BLOCK ORDER_ENTRY /ROW=14 /COL=10 & /FACILITY=ORDER_ENTRY

5-12

Blocks and Block Qualifiers IAF 8.0 DML

MENU Blocks

MENU Blocks
General Purpose
A menu block describes a finite number of options that IAF is to display in a menu format. For each option that the given menu is to include, the menu block specifies a tag that identifies the option and facilitates its selection, a description of the option, and a DML statement that is to execute when an end user selects the option.

Block Statement Syntax

Following is the syntax for the MENU_BLOCK statement, which is the block type statement to use for menu blocks:
MENU_BLOCK [block_name] & /ROW=numeric_expression & /COL=numeric_expression & /item_qualifier[/item_qualifier[...]] [/qualifiers]

where /item_qualifier is one of the following qualifiers:

/ITEM=tag_string_expression,description_string_expression,(dml_statement) /ITEM_IF=(condition_expression),tag_string_expression,description_string_expression,(dml_statement)

Implicit Block Actions

When executing a menu block, IAF displays a bordered window containing a column of option tags and a column of associated option descriptions. A menu block can indicate any number of /ITEM and/or /ITEM_IF qualifiers to define the options the menu is to include. Specifically, each qualifier indicates the tag, description, and dml statement to execute for the option it defines. Additionally, the /ITEM_IF qualifier specifies a condition expression which must be true for the given option to appear in the menu. Upon initially executing the menu block, IAF displays the default option tag in reverse video. The menu block can indicate a default option via the /SOURCE qualifier. If the menu block does not include a /SOURCE qualifier, the menus first option is the default option. The end user can move the cursor to a menu option by typing a portion of its tag or pressing the GM_UP or GM_DOWN key. The end user can then select the option by pressing the GM_EXIT_FORWARD,

Blocks and Block Qualifiers IAF 8.0 DML

5-13

MENU Blocks

GM_FORWARD, GM_SELECT_ROW, or GM_CR key. IAF executes any DML code specified for the selected option via the given /ITEM or /ITEM_IF qualifier. By default, IAF re-executes the menu block after executing any DML associated with the selected option. This behavior continues until the end user selects an option that performs an exit (for example; and EXIT option), or presses the GM_EXIT or GM_BACK key.

Special Considerations
Menu blocks require the use of a screen window. However, a PROCEDURE form has no implicit screen window. Therefore, to execute a menu block defined within a PROCEDURE form, IAF uses the first screen window belonging to a parent form of the PROCEDURE form. The screen window that a menu block uses can be as small as one row by one column (even if the menu display is larger.) It is possible to create a scrolling menu by using the /HEIGHT block qualifier. For details on using the /HEIGHT qualifier to create a scrolling menu, refer to this chapters description of the /HEIGHT qualifier. If the base form on which a menu block is to display its menu has no border (as a result of its form header statement including the /NOBORDER qualifier) and contains no other blocks, IAF displays the menu in its complete state.

5-14

Blocks and Block Qualifiers IAF 8.0 DML

MENU Blocks

Qualifiers
The following qualifiers are applicable to the MENU_BLOCK statement. For details regarding these qualifiers, refer to this chapters Block Qualifiers section.
/BACK /COL /EXIT /EXIT_FORWARD /HEIGHT /ITEM /ITEM_IF /NOREPEAT /OPT /ROW /SOURCE /SOURCE_IF /TARGET /TITLE /USE_IF

Example
MENU_BLOCK INQ_TYPE /ROW=7 /COL=35 & /ITEM=PARTS, Parts Inquiry, (PERFORM PRT_INQ) & /ITEM=ORDERS, Orders Inquiry, (PERFORM ORD_INQ) & /ITEM=CUSTOMERS, Customer Inquiry, (PERFORM CST_INQ) &
/ITEM_IF=(#PREFERRED=Y), DISCOUNTS,Discount Inquiry, (PERFORM DSC_INQ) &

/ITEM=EXIT, Exit,(EXIT)

Blocks and Block Qualifiers IAF 8.0 DML

5-15

Examples: Applying MENU Block Pulldown Menus

Examples: Applying MENU Block Pulldown Menus

Note: References cross over to iBrowser display and implementation. As an example of MENU block application, IAF Client for Windows Pro supports two MENU block styles. These styles are windowed (the standard IAF MENU block) and pulldown, and are not mutually exclusive. Either style or both may be used at any given time. The GCW Pro-specific GEM_MENU_STYLE SCV controls how IAF displays menus. This SCV is automatically set upon selecting the MENU STYLE option from the Options pulldown menu. For more details regarding the MENU STYLE option, refer to the IAF Client for Windows Pro User Guide, OPTIONS MENU chapter. If a given MENU block does not include the /TITLE qualifier, the title for the pulldown version of the menu is User Menu. The following table lists and describes the MENU block qualifiers that facilitate creating pulldown menus. Qualifier /BEGIN_SUB_MENU=title Description This qualifier indicates that GCW Pro is to start a sub-menu with the given title and causes GCW Pro to display a small arrow to the right of the submenus description to indicate that it is a sub-menu (not just an option). This qualifier marks the end of a submenu definition. This qualifier indicates that GCW Pro is to start a new pulldown, with the given title, to the right of the current menu.

/END_SUB_MENU /SPLIT=title

5-16

Blocks and Block Qualifiers IAF 8.0 DML

Examples: Applying MENU Block Pulldown Menus

These qualifiers make it possible to define several pulldown menus and sub-menus in a single MENU block, and apply only to GCW Pro. If the given DML code is to be portable, it should be enclosed in a test for MSDOS as the following example indicates. The following example produces two pulldown menus, with the second pulldown having a submenu, which in turn has a sub-menu, thus illustrating that sub-menus can be nested.
IF (%OPERATING_SYSTEM=MS-DOS) MENU_BLOCK MENU /ROW=7 /COL=23 & /TITLE=&Cash Transactions & /ITEM=(ADD),(Add Transactions),(PERFORM ADD) &
/ITEM=(MODIFY),(Modify Transactions),(PERFORM MODIFY) &

/SPLIT=Products & /ITEM=(DELETE),(Delete Products),(PERFORM DELETE) & /ITEM=(SHOW),(Show Products),(PERFORM SHOW) & /BEGIN_SUB_MENU=Other Functions & /ITEM=(LIST),(List Products),(PERFORM PLIST) & /BEGIN_SUB_MENU=Additional Details & /ITEM=(LIST),(List Groups),(PERFORM GLIST) & /ITEM=(EXIT),(Product Details),(PERFORM DETAILS) & /END_SUB_MENU & /ITEM=(EXIT),(Exit System),(EXIT) & /END_SUB_MENU END_IF

This example also illustrates how accelerator key sequences can be set up by placing the ampersand character (&) in the menu title that the /TITLE qualifier specifies. An accelerator key sequence consists of the Alt key with another key. To specify the title character that is to form the latter portion of the accelerator key sequence, place the ampersand before that character. In the example, the ampersand directly precedes the character, C. Therefore Alt-C activates the Cash Transactions menu.

Blocks and Block Qualifiers IAF 8.0 DML

5-17

Examples: Applying Block Button Menus

Examples: Applying Block Button Menus

It is possible to represent a MENU block as a series of buttons by appending the /BUTTONS qualifier to the MENU block. The /BUTTONS qualifiers syntax is as follows:
/BUTTONS=row,column,buttons_per_row

where row indicates the form row in which to place the top of the menu, column indicates the form column in which to place the leftmost column of the menu, and buttons_per_row indicates the number of buttons to place in each menu row. IAF ignores this qualifier in character-cell environments. Therefore, it is not necessary to test for MS-DOS to make the DML code portable. The row and column information that the /BUTTONS qualifier specifies overrides the MENU blocks /ROW and /COL information. This allows for a portable menu for which positioning can be customized for both Windows and character-cell displays. The following example produces a menu beginning in row 7 and column 25 with two rows consisting of three buttons each:
MENU_BLOCK MENU /ROW=7 /COL=25 & /ITEM=(ADD),(Add Part Master),(PERFORM ADD) & /ITEM=(MODIFY),(Modify Part Master),(PERFORM MODIFY) & /ITEM=(DELETE),(Delete Part Master),(PERFORM DELETE) & /ITEM=(SHOW),(Show Part Master),(PERFORM SHOW) & /ITEM=(LIST),(),(PERFORM LIST) & /ITEM=(EXIT),(Exit),(EXIT) & /BUTTONS=7,25,3

To produce a single column of buttons, the example would specify one button per row. To produce one row of six buttons, the example would specify six buttons per row.

5-18

Blocks and Block Qualifiers IAF 8.0 DML

OUTPUT Blocks

OUTPUT Blocks
General Purpose
An output block specifies data that IAF is to display on the screen and indicates the source of the data. The various qualifiers available for use with output blocks facilitate formatting the data for display, among other things.

Block Statement Syntax

Following is the syntax for the OUTPUT_BLOCK statement, which is the block type statement to use for output blocks:
OUTPUT_BLOCK [block_name] & /ROW=numeric_expression & /COL=numeric_expression & /SOURCE=expression [/qualifiers]

Note that the /ROW and /COL qualifiers are mandatory for the OUTPUT_BLOCK statement unless it resides within a REPORT form.

Implicit Block Actions

When IAF executes an output block, it displays on the current form the output data that the output blocks mandatory /SOURCE qualifier specifies. IAF does not perform any domain validation (explicit or implicit) on the output data unless the given OUTPUT_BLOCK statement includes the /DOMAIN qualifier.

Special Considerations
Output blocks require the use of a screen window. However, a PROCEDURE form has no implicit screen window. Therefore, to execute an output block defined within a PROCEDURE form, IAF uses the first screen window belonging to a parent form of the PROCEDURE form. The default height of an output blocks display area is one row. This causes IAF to display only the first line of output data for fields that have a DOCUMENTARY native datatype. However, it is possible to accommodate multiple output lines via the /HEIGHT and /LENGTH block qualifiers.

Blocks and Block Qualifiers IAF 8.0 DML

5-19

OUTPUT Blocks

If an output block specifies a table field via the /SOURCE or /USING qualifier, IAF applies all relevant details from the given fields data dictionary definition (output mask, length, and so on) to the output data. It is possible to override a given element of the fields definition for the output data by using the appropriate output block qualifier ( /OUTPUT_MASK, /LENGTH, etc.) If an output block specifies an output mask for a date/time field via the /OUTPUT_MASK qualifier and the mask includes the !LM (long month) mask token, the output block may also have to include the /LENGTH qualifier to accommodate the long month names. For details regarding output masks, refer to this manuals INPUT AND OUTPUT MASKS appendix.

Qualifiers
The following qualifiers are applicable to the OUTPUT_BLOCK statement. For details regarding these qualifiers, refer to this chapters Block Qualifiers section.
/ABSOLUTE_POSITION /ATTRIBUTES /BREAK /COL /DOMAIN /HEADING /HEIGHT /LEN /NOHEADING /NOUNDERLINES /OUTPUT_MASK /PDF /ROW /PROMPT /SOURCE /SOURCE_IF /TARGET /TOTAL /USE_IF /USING

Example
OUTPUT_BLOCK SHOW_NAME /ROW=10 /COL=50 & /SOURCE=CUSTOMERS(NAME)

5-20

Blocks and Block Qualifiers IAF 8.0 DML

PAUSE Blocks

PAUSE Blocks
General Purpose
A pause block causes IAF to display the Press RETURN to continue... prompt and wait for the end user to press the GM_CR key before it continues to execute the given form.

Block Statement Syntax

PAUSE_BLOCK [block_name] [/qualifiers]

Although there are no mandatory qualifiers for the PAUSE_BLOCK statement, it is advisable to include the /ROW and /COL qualifiers. If a given PAUSE_BLOCK statement does not include the /ROW qualifier, the default display row for the pause block is 1. Likewise, if the PAUSE_BLOCK statement does not include the /COL qualifier, the default display row for the pause block is 1.

Implicit Block Actions

IAF displays the Press RETURN to continue... prompt and waits for the end user to press the GM_CR key. Once the end user presses a key, IAF continues executing the given form.

Special Considerations
Pause blocks require the use of a screen window. However, a PROCEDURE form has no implicit screen window. Therefore, to execute a pause block defined within a PROCEDURE form, IAF uses the first screen window belonging to a parent form of the PROCEDURE form. If a pause block resides on the last line of a forms window, and the form calls a sub-form whose form header statement includes the /REMAIN qualifier, and an input error causes IAF to display an error message, IAF re-displays the calling form but not the called form. To avoid this problem, do not place a pause block on the last three lines of a form that calls a form whose form header statement includes the /REMAIN qualifier.

Blocks and Block Qualifiers IAF 8.0 DML

5-21

PAUSE Blocks

Qualifiers
The following qualifiers are applicable to the PAUSE_BLOCK statement. For details regarding these qualifiers, refer to this chapters Block Qualifiers section.
/BACK /COL /EXIT /EXIT_FORWARD /PROMPT /ROW /USE_IF

Example
PAUSE_BLOCK /ROW=20 /COL=40

5-22

Blocks and Block Qualifiers IAF 8.0 DML

SIGNATURE_BLOCK

SIGNATURE_BLOCK
General Purpose
The SIGNATURE_BLOCK requests a single or double electronic signature from an end-user and validates that input. It provides the application developer with the means to perform an interactive electronic signature. A SIGNATURE_BLOCK brings up a window in the charactercell user interface and a dialog in the Windows user interface. The window or dialog contains input areas where the end-user specifies purpose, username and password. In the case of a double electronic signature, the window or dialog contains input areas for two sets of usernames and passwords. Please refer to Appendix F, Electronic Signature and Audit for additional information.

Block Statement Syntax

Following is the syntax for the SIGNATURE_BLOCK statement:
SIGNATURE_BLOCK [/AUDIT=audit-file-specification] [/DATETIME=date-time] [/DOUBLE] [/FACILITY=facility-name] [/NOAUDIT] [/OPTIONS=domain-options] [/PURPOSE=purpose] [/SUCCESS=(success-dml)] [/TITLE=title] [/USERNAME1=username_1] [/USERNAME2=username_2] [/USER1=user-defined-1] [/USER2=user-defined-2] [/USER3=user-defined-3] [/USER4=user-defined-4] [/USER5=user-defined-5] [/VALIDATION_FORM=form-name] [/Additional-qualifiers]

Blocks and Block Qualifiers IAF 8.0 DML

5-23

SIGNATURE_BLOCK

Implicit Block Actions

The username(s) and password(s) entered by the end-user are authenticated by the operating system regardless of whether or not an explicit VALIDATION_FORM is specified.

Special Considerations
In order to use a SIGNATURE_BLOCK on the UNIX platform, the IAF monitor must be running. On the UNIX platform, the system-level authentication of usernames and passwords is carried out by the IAF monitor on behalf of the user executing the SIGNATURE_BLOCK. If the IAF monitor is not running or is not responding, a message to that effect will be displayed and the user will be re-prompted for entries. The user may then exit or cancel the signature block. After the user has made his entries, any validation form specified is called before the username(s) and password(s) are authenticated by the operating system. If /DOUBLE or /USERNAME2=username-2 is specified, this indicates a double electronic signature. The List-Of-Values (/LOV) qualifier and related qualifiers, when used with a SIGNATURE_BLOCK, apply only to the purpose input field. An audit record is appended to the audit file (unless /NOAUDIT is specified) regardless of the success or failure of the validation of the signature(s). If the authentication fails, a record is written to the audit file and the user will normally be prompted to amend the invalid signature entries.

Specific Qualifiers
The following qualifiers have a specific definition in relation to a SIGNATURE_BLOCK: /AUDIT /DATETIME /DOUBLE /ERASE /FACILITY /FAILURE /NOAUDIT
5-24 Blocks and Block Qualifiers IAF 8.0 DML

SIGNATURE_BLOCK

/OPTIONS /PURPOSE /RECALL /SAVE /SUCCESS /TITLE /USERNAME1 /USERNAME2 /USER1 /USER2 /USER3 /USER4 /USER5 /VALIDATION_FORM

Additional Qualifiers
The following qualifiers are also applicable to the SIGNATURE_BLOCK statement. For details regarding these qualifiers, please refer to the chapter on Blocks and Block Qualifiers in the IAF Data Manipulation Language manual. /BACK /EXIT /LOV /LOV_AUTO_SELECT /LOV_DATA /LOV_FIRST /LOV_NOHEADING /LOV_NOSEARCH /LOV_REDUCED_TO /LOV_SECONDARY /LOV_SELECTION

Blocks and Block Qualifiers IAF 8.0 DML

5-25

SIGNATURE_BLOCK

/LOV_SORTED_BY /LOV_WITH /NOLOV_DATA /USE_IF

Exit Status
After the SIGNATURE_BLOCK statement executes, the special variable %STATUS is set to one of the following values: %SUCCESS if the signature(s) are accepted as valid by the optional validation form and successfully authenticated by the operating system. %EXIT if the user exited from the signature block or clicked on the CANCEL button in the dialog, or if the validation form returned a %EXIT status. If a /EXIT qualifier is defined and executes, then %STATUS is set to %SUCCESS before the associated DML is executed. %BACK if the user hit the GM_BACK key on the first line in the signature block, or if the validation form returned a %BACK status.

5-26

Blocks and Block Qualifiers IAF 8.0 DML

YESNO Blocks

YESNO Blocks
General Purpose
A yes/no block prompts the end user for a response to a yes/no question (ithe only valid responses are Yes and No.)

Block Statement Syntax

YESNO_BLOCK [block_name] & /ROW=numeric_expression & /COL=numeric_expression [/qualifiers]

Implicit Block Actions

When executing a yes/no block, IAF displays its default response. If the block does not indicate a default response via the /SOURCE or /SOURCE_IF qualifier, the value of the /TARGET qualifiers expression serves as the default response. If the block does not include a /TARGET qualifier, the default response for the block is No. Yes/no blocks are not case-sensitive. If the end users response to a yes/no block begins with Y, y, N, or n, the response is valid, and IAF displays the full Yes or No in the input area after the end user presses the GM_CR key for the entry.

Special Considerations
Yes/no blocks require a screen window. However, a PROCEDURE form has no implicit screen window. Therefore, to execute a yes/no block in a PROCEDURE form, IAF uses the first screen window of a parent form of the PROCEDURE form. If a yes/no block resides on form windows last line, the form calls a subform whose form header statement includes the /REMAIN qualifier, and an input error causes IAF to display an error message, IAF re-displays the calling form but not the called form. To avoid this problem, do not place a yes/no block on the last three lines of a form that calls a form whose form header statement includes /REMAIN.

Blocks and Block Qualifiers IAF 8.0 DML

5-27

YESNO Blocks

Qualifiers
The following qualifiers are applicable to the YESNO_BLOCK statement. For details regarding these qualifiers, refer to this chapters Block Qualifiers section.
/BACK /COL /EXIT /EXIT_FORWARD /FAILURE /HEADING /NOUNDERLINES /PROMPT /ROW /SOURCE /SOURCE_IF /SUCCESS /TARGET /USE_IF

Example
YESNO_BLOCK CONFIRM /ROW=14 /COL=20 /PROMPT=All order details OK & /SUCCESS=(ADD TO SALES_ORDERS)

5-28

Blocks and Block Qualifiers IAF 8.0 DML

Examples: Applying YESNO Block Checkboxes

Examples: Applying YESNO Block Checkboxes

Note: User interface development information applies in many cases to iBrowser as well. The DML includes the /CHECKBOX qualifier for YESNO blocks to allow a Windows checkbox to be the vehicle by which end users respond to YESNO blocks. The end user can toggle the checkbox state via the mouse or the keyboard. The keyboard toggle is the space bar. A checked checkbox returns a YES or success status. An unchecked checkbox returns a NO or failure status. On platforms other than Windows, if an end user presses the GM_EXIT_FORWARD key at any DML form input that logically precedes a YESNO block, a form exit does not take place. Instead, DML execution pauses at the YESNO block to allow the end user to respond to the prompt. However, in IAF Client for Windows Pro, if an end user presses GM_EXIT_FORWARD at any DML form input that logically precedes a YESNO block checkbox, no such pause takes place at the YESNO block checkbox. The /SOURCE qualifier provides for specifying a default checkbox state for a YESNO block. The example on the following page uses the /SOURCE qualifier to specify Y, indicating that, by default, the checkbox is to be checked.
YESNO_BLOCK ACCOUNT_FLAG /ROW=5 /COL=20 & /CHECKBOX & /PROMPT=(Account Due) & /SOURCE=(Y) & /TARGET=ACCOUNT_MASTER(ACCOUNT_DUE)

Blocks and Block Qualifiers IAF 8.0 DML

5-29

Examples: Applying YESNO Block Buttons

Examples: Applying YESNO Block Buttons

Note: User interface development information applies in many cases to iBrowser as well. The DML includes the /BUTTONS qualifier for YESNO blocks to allow buttons to be the vehicles by which end users respond to YESNO blocks. By default, GCW Pro labels the buttons OK and Cancel, where the OK button causes an immediate exit forward, and the Cancel button causes an immediate form exit. The YESNO blocks /ROW qualifier indicates the row on which to position the buttons. IAF Client for Windows Pro automatically centers the buttons horizontally on the form. You can override the default labels for the buttons by optionally specifying replacement labels in a comma-separated list via the /BUTTONS qualifier. The following examples illustrate the use of the /BUTTONS qualifier.
YESNO_BLOCK OKCANCEL /ROW=20 /COL=20 & /BUTTONS

YESNO_BLOCK ACTION /ROW=22 /COL=40 & /BUTTONS=Accept,Reject

5-30

Blocks and Block Qualifiers IAF 8.0 DML

Block Qualifiers

Block Qualifiers
A block qualifier represents an option that you can activate by appending the qualifier to a block type statement to which it applies. The following table lists all available block qualifiers, and for each one, indicates the block type(s) to which it applies. The table contains a column for each block type. If the column contains an X where a given qualifier row and block type column intersect, it means that the qualifier applies to that block type. Qualifier DML /ABSOLUTE_POSITION /ATTRIBUTES /AUDIT /BACK /BREAK /COL /DATETIME /DISPLAY_LENGTH /DISPLAY_ONLY /DOMAIN /DOUBLE /ERASE /EXIT /EXIT_FORWARD /FACILITY /FAILURE /HEADING /HEIGHT X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X Input X X Menu Block Type Output X X X X X Pause Yes/No Item Sig Block

Blocks and Block Qualifiers IAF 8.0 DML

5-31

Block Qualifiers

Qualifier DML /INPUT_MASK /ITEM /ITEM_IF /LEN /LOV /LOV_AUTO_SELECT /LOV_COL /LOV_DATA /LOV_FIRST /LOV_HEIGHT /LOV_NOHEADING /LOV_NOSEARCH /LOV_REDUCED_TO /LOV_ROW /LOV_SECONDARY /LOV_SELECTION /LOV_SORTED_BY /LOV_WIDTH /LOV_WITH /NEW /NOAUDIT /NOCLEAR_BUFFER /NODOMAIN /NOHEADING X X X X X X X X X X X X X X X X X X X Input X X X Menu

Block Type Output Pause Yes/No Item Sig Block

X X X

X X

X X X

X X X

5-32

Blocks and Block Qualifiers IAF 8.0 DML

Block Qualifiers

Qualifier DML /NOLOV_DATA /NOREPEAT /NOUNDERLINES /OPT /OPTIONS /OUTPUT_MASK /PDF /PROMPT /PROTECT /PURPOSE /RECALL /ROW /SAVE /SOURCE /SOURCE_IF /SUCCESS /TAG /TAG_LENGTH /TARGET /TITLE /TOTAL /USE_IF /USER 1-5 /USER_KEYn X X X X X X X X X X X X X X Input X X Menu

Block Type Output Pause Yes/No Item Sig Block X

X X X X X X X

X X X X X X X X X X X X X X X X X X X X X X X X X

Blocks and Block Qualifiers IAF 8.0 DML

5-33

Block Qualifiers

Qualifier DML /USERNAME1 /USERNAME2 /USING /VALIDATION_FORM X Input Menu

Block Type Output Pause Yes/No Item Sig Block X X X X

5-34

Blocks and Block Qualifiers IAF 8.0 DML

Block Qualifiers

The remainder of this section provides detailed descriptions of the qualifiers that apply to one or more block statements. Unless otherwise noted, a given qualifier can be specified only once per block. If a qualifier allowing only one instance per block is specified more than once for a given block, IAF ignores all but the last instance of the qualifier. For details on a particular block statement and the qualifiers that apply to it, refer to this chapters section pertaining to that block type (for example; DML, Input, Item, Menu, Output, Pause, Yes/No.) Note that the given qualifier examples do not necessarily include other qualifiers (/ROW, /COL, and so on) that the given block statement requires.

Blocks and Block Qualifiers IAF 8.0 DML

5-35

/ABSOLUTE_POSITION

/ABSOLUTE_POSITION
Syntax
/ABSOLUTE_POSITION

Description
This qualifier indicates that IAF is to position the block relative to the form windows boundaries rather than relative to the current table entry in a TABLE_EDIT form. This qualifier is intended for use with input and output blocks in TABLE_EDIT forms.

Example
OUTPUT_BLOCK BATCH_TOTAL /ROW=21 /COL=30 & /ABSOLUTE_POSITION & /PROMPT=FIELD_PROMPT(TOTAL_VALUE) & /USING=ORDERS(TOTAL_VALUE) & /SOURCE=#BATCH_TOTAL

This output block displays a running total at the bottom of the given forms window.

5-36

Blocks and Block Qualifiers IAF 8.0 DML

/ATTRIBUTES

/ATTRIBUTES
Syntax
/ATTRIBUTES=keyword[,keyword[,...]]

Description
This qualifier allows you to indicate the input foreground display attributes for an input block or the output background display attributes for an output block. The input foreground display is the area in which input occurs. The output background display is the area in which output displays. By default, IAF uses the current system input foreground attributes for an input block and adds to these attributes any attributes that the /ATTRIBUTES qualifier specifies. However, if the /ATTRIBUTES qualifier indicates the FORCE keyword, IAF uses only the attributes that the /ATTRIBUTES qualifiers specifies. Likewise, by default IAF uses the current system background attributes for an output block and adds to these attributes any attributes that the /ATTRIBUTES qualifier specifies. However, if the /ATTRIBUTES qualifier specifies the FORCE keyword, IAF uses only the attributes that the /ATTRIBUTES qualifiers specifies. Note that for output blocks in TABLE_EDIT forms, the attributes that the /ATTRIBUTES qualifier specifies appear only once the end user has selected a record. Also note that IAF ignores any /ATTRIBUTES qualifiers that output blocks in REPORT forms indicate. The /ATTRIBUTES qualifier can indicate any combination of attribute keywords. However, it may not indicate any keyword more than once. The table on the following page lists and describes the effects of the attribute keywords that are valid for use with this qualifier. Keyword BLINK BOLD FORCE Effect The input or output area blinks. The input or output area displays in bold. The input or output area uses only the attributes that the /ATTRIBUTES block qualifier specifies.

Blocks and Block Qualifiers IAF 8.0 DML

5-37

/ATTRIBUTES

Keyword NONE REVERSE UNDERLINE

Effect The input or output area has no special display attributes. The input or output area displays in reverse video. The input or output area is underlined.

Example
/ATTRIBUTES=BOLD,REVERSE

5-38

Blocks and Block Qualifiers IAF 8.0 DML

/AUDIT

/AUDIT
Syntax
/AUDIT=audit-file-specification

Description
This optional qualifier specifies the file to which the audit record is written. Audit-file-specification can be a quoted literal, a variable, a function, a table field or an expression in parentheses. An audit record is always written unless the /NOAUDIT qualifier is specified. You may not specify both the /AUDIT and the /NOAUDIT qualifiers on the same SIGNATURE_BLOCK. Please see the section about the audit log file for more information on its format, contents and naming.

Example
/AUDIT="signature-audit-filename

Blocks and Block Qualifiers IAF 8.0 DML

5-39

/BACK

/BACK
Syntax
/BACK=(dml_statement)

Description
This qualifier allows you to indicate the action IAF is to take when an end user presses the GM_BACK key at an input, menu, pause, or yes/no block. By default, when an end user presses GM_BACK, IAF transfers control to the last previously executed input, menu, pause, or yes/no block on the current form. If the block that specifies this qualifier is the first block on the form, and an end user presses the GM_BACK key at the block, the form does not immediately exit as it would by default. Instead, IAF executes the DML statement that the /BACK qualifier specifies. Then, if the statement did not transfer control to another location in the program (for example; the statement was not a GOTO or other branching statement), the form exit takes place. For a list of DML statements that the /BACK qualifier can indicate, refer to this manuals Executing DML Statements Via Qualifiers appendix.

Examples
/BACK=(GOTO GET_DISC_PERCENTAGE) /BACK=(CONTINUE ROLLBACK)

5-40

Blocks and Block Qualifiers IAF 8.0 DML

/BREAK

/BREAK
Syntax
/BREAK=positive_integer

Description
This qualifier is applicable only to output blocks on REPORT forms, and can be specified more than once per block. This qualifier allows you to indicate a value indicating the level break for which IAF is to display the given output blocks data. A level break occurs when a specified break fields value changes from one record to the next. IAF assigns a sequential level break number to each level break that a given form specifies via a /BREAK qualifier. A form can use level breaks to trigger actions, such as printing extra lines or totals. For details on using the /BREAK and /TOTAL qualifiers together on an output block, refer to this sections description of the /TOTAL qualifier.

Example
Given the following REPORT_FORM statement:
REPORT_FORM MAIN /TABLE=ORDERS & /SORTED_BY=(REGION,CUSTOMER_ID) & /BREAK=ORDERS(REGION) & /BREAK=ORDERS(CUSTOMER_ID)

break 1 occurs when the ORDERS(REGION) table fields value changes from one record to the next, and break 2 occurs when the ORDERS(CUSTOMER_ID) table fields value changes from one record to the next. Based upon these break levels, IAF displays the following output blocks data only upon encountering a new ORDERS(REGION) value:
OUTPUT_BLOCK REGION /SOURCE=ORDERS(REGION) /BREAK=1

Likewise, IAF displays the following output blocks data only upon encountering a new ORDERS(CUSTOMER_ID) value:
OUTPUT_BLOCK CUSTOMER_ID /SOURCE=ORDERS(CUSTOMER_ID) /BREAK=2

Blocks and Block Qualifiers IAF 8.0 DML

5-41

/CHEADING

/CHEADING
Syntax
/CHEADING= string_expression

Description
This qualifier allows you to indicate the column heading for an input block, output block, or yes/no block in a TABLE_EDIT form, or for an output block in a REPORT form. IAF centers the heading within the given column, without truncating the heading to the columns length (for example, the heading can extend over several columns). You can include a comma in the heading expression to force the heading portion before the comma to display on one line, and the heading portion after the comma to display on the next line. A heading can display over no more than two lines. By default, IAF generates a column heading when it executes the given form. You can center, left-justify, or right-justify each column heading over its related column via the /HEADING, /CHEADING, /LHEADING, or /RHEADING block qualifier. For details regarding the /HEADING, /LHEADING and /RHEADING block qualifiers, refer to their descriptions in this section.

Example
/CHEADING=Customer Name

5-42

Blocks and Block Qualifiers IAF 8.0 DML

/COL

/COL
Syntax
/COL=numeric_expression

or
/COL=keyword

Description
/COL=numeric_expression

This qualifiers characteristics depend upon the block statement that specifies it. The /COL qualifier is mandatory for input, item, menu, output, and yes/no blocks, and is recommended for use with pause blocks. The /COL qualifier is also mandatory for output blocks that do not reside within REPORT forms. The table on the following page describes the effect of the /COL qualifier for each block statement to which it applies. Block Statement INPUT_BLOCK /COL Qualifiers Effect This qualifier specifies the first column of the input area relative to the form windows left edge. This qualifier specifies the column in which the first letter of the given items tag is to reside relative to the form windows left edge. This qualifier specifies the column in which the left-most column of the given menu is to reside relative to the form windows left edge. This qualifier specifies the first column of the output area relative to the form windows left edge. This qualifier specifies the column that is to be the input area relative to the form windows left edge. By default, IAF displays the last character of the pause blocks prompt two spaces to the left of the column that the /COL qualifier specifies.

ITEM_BLOCK

MENU_BLOCK

OUTPUT_BLOCK

PAUSE_BLOCK

Blocks and Block Qualifiers IAF 8.0 DML

5-43

/COL

Block Statement YESNO_BLOCK

/COL Qualifiers Effect This qualifier specifies the first column of the input area relative to the form windows left edge. By default, IAF displays the last character of the yes/no blocks prompt two spaces to the left of the column that the /COL qualifier specifies.

/COL=keyword
This qualifier applies only to output blocks on REPORT forms. The following table lists and describes the keywords that this qualifier can indicate. Keyword CENTER or CENTRE LEFT RIGHT Effect Center the output horizontally on the report page. Left-justify the output on the report page. Right-justify the output on the report page.

Examples
/COL=25 /COL=(#BASE_COL+10) /COL=LEFT

5-44

Blocks and Block Qualifiers IAF 8.0 DML

/DATETIME

/DATETIME
Syntax
/DATETIME=date-time

Description
This optional qualifier specifies the location in which to store the date and time at which the electronic signature validation took place. This datetime is defined as occurring after the interactive dialog ends, after the optional validation form returns, after the usernames and passwords are authenticated by the operating system, and just prior to the audit record, if any, being written. The date-time can be any variable or table field that is acceptable as the target of an input block.

Example
/DATETIME=#sig-date-time

Blocks and Block Qualifiers IAF 8.0 DML

5-45

/DISPLAY_LENGTH

/DISPLAY_LENGTH
Syntax
/DISPLAY_LENGTH=numeric_expression

Description
This qualifier allows you to indicate the display size of an input blocks input area and is especially useful when the blocks position on the form does not allow the input area to accommodate the desired number of characters. If the display length that this qualifier specifies is less than the input blocks default length or the length that the input blocks /LEN qualifier specifies (if present), the input area becomes a scrolling input area. IAF ignores the display length if it is greater than or equal to the blocks length, or if the given block statement also includes the /HEIGHT qualifier. For more information on block lengths and the /LEN qualifier, refer to this sections description of the /LEN qualifier. For details on the /HEIGHT qualifier, refer to its description in this section.

Example
INPUT_BLOCK LAST_NAME /ROW=5 /COL=10 & /TARGET=EMPLOYEES(LAST_NAME) & /LEN=20 /DISPLAY_LENGTH=12

Although the input area that this example produces has a display size of only 12 characters, it can accept as many as 20 characters of input data.

5-46

Blocks and Block Qualifiers IAF 8.0 DML

/DISPLAY_ONLY

/DISPLAY_ONLY
Syntax
/DISPLAY_ONLY

Description
This qualifier indicates that the DML code in the DML block that specifies this qualifier is to execute only when IAF displays data as a result of executing the DISPLAY DEFAULTS statement. This facilitates special processing when automatically displaying a TABLE_EDIT forms first screen of data via the DISPLAY DEFAULTS statement. For details on the DISPLAY DEFAULTS statement, refer to this manuals LANGUAGE STATEMENTS chapter.

Example
BEGIN_BLOCK /DISPLAY_ONLY CREDIT_DESC IF (CUSTOMERS(CREDIT_CODE)=) #SOURCE=No Credit Limit ELSE
CHECK_DOMAIN /TARGET=CUSTOMERS(CREDIT_CODE) /DOMAIN=CREDIT_CODES

#SOURCE=CREDIT_CODES(DESCRIPTION) END_IF END_BLOCK OUTPUT_BLOCK CREDIT_CODE_DESC /COL=20 /ROW=5 /SOURCE=#SOURCE

Blocks and Block Qualifiers IAF 8.0 DML

5-47

/DOMAIN

/DOMAIN
Syntax
/DOMAIN=table_name

Description
This qualifier allows you to indicate a table for which IAF is to perform domain validation against the blocks target table (if the block is an input block) or the blocks source table (if the block is an output block.) This qualifier can be specified only once per block (unlike the CHECK_DOMAIN statements /DOMAIN qualifier.)
Input Block Domain Validation

An input blocks target table is the table that its /TARGET or /USING qualifier specifies. If multiple domains link the target table and domain table (for example; the table this qualifier specifies), IAF performs the domain check on the table field that the /TARGET or /USING qualifier specifies. IAF determines if the input data exists in the domain field in the table that the /DOMAIN qualifier specifies. This facilitates operations such as code look-ups. Note that the target and domain table may be the same. If the domain validation succeeds (the data exists in the domain table), IAF places the appropriate record from the domain table in the user buffer associated with the table that the /DOMAIN qualifier specifies. This makes the records data available for subsequent use. If the domain validation fails (for example; the data does not exist in the domain table), IAF displays an error message and prompts the end user to re-enter the data. Note that IAF validates an input blocks implicit domains automatically regardless of whether or not the given INPUT_BLOCK statement includes the /DOMAIN qualifier. The /DOMAIN qualifier causes IAF to validate the input blocks explicit domain. Also note that, unlike the CHECK_DOMAIN statement, the INPUT_BLOCK statement does not handle multiple /DOMAIN qualifiers. If IAF encounters more than one /DOMAIN qualifier on an input block, it ignores all but the last one.

5-48

Blocks and Block Qualifiers IAF 8.0 DML

/DOMAIN

Output Block Domain Validation

An output blocks source table is the table that the blocks /SOURCE or /USING qualifier specifies. If multiple domains link the source table and the domain table (for example; the table that this qualifier specifies), IAF performs the domain check on the table field that the /SOURCE or /USING qualifier specifies. IAF determines if the output data exists in the domain field in the table that the /DOMAIN qualifier specifies. If the domain validation succeeds (for example; the data exists in the domain table), IAF places the appropriate record from the domain table in the user buffer associated with the table that the /DOMAIN qualifier specifies. This makes the records data available for subsequent use. If the domain validation fails (for example; the data does not exist in the domain table), IAF does not display an error message. Note that IAF validates implicit and explicit domains only for output blocks that indicate the /DOMAIN qualifier. Also note that, unlike the CHECK_DOMAIN statement, the OUTPUT_BLOCK statement does not handle multiple /DOMAIN qualifiers. If IAF encounters more than one /DOMAIN qualifier on an output block, it ignores all but the last one. For details on user buffers and domains, refer to the IAF Users Guide. For information on qualifiers that activate options related to domain validation, refer to this sections description of the /PROTECT and /NEW qualifiers.

Examples
INPUT_BLOCK GET_PART_CODE /ROW=5 /COL=10 & /TARGET=SALES_ORDER_LINES(PART_CODE) /DOMAIN=PARTS

If the entered part code exists in the PARTS table (for example; it is valid), IAF places the PARTS table record for the given part in the user buffer associated with the PARTS table.
OUTPUT_BLOCK SHOW_PART_CODE /ROW=5 /COL=18 & /SOURCE=SALES_ORDER_LINES(PART_CODE) /DOMAIN=PARTS

If the part code to output exists in the PARTS table (for example; it is valid), IAF places the PARTS table record for the given part in the user buffer associated with the PARTS table.

Blocks and Block Qualifiers IAF 8.0 DML

5-49

/DOUBLE

/DOUBLE
Syntax
/DOUBLE

Description
This optional qualifier indicates that a double signature is required. This causes the end-user to be prompted for two sets of usernames and passwords. The user is not permitted to enter same username twice. When you use the /USERNAME2 qualifier, you may also use the /DOUBLE qualifier but it is unnecessary.

5-50

Blocks and Block Qualifiers IAF 8.0 DML

/ERASE

/ERASE
The /ERASE qualifier is used to erase saved authentication information. The saved authentication information is erased as the last operation performed by the SIGNATURE_BLOCK or SIGNATURE statement. Thus if both /RECALL and /ERASE are specified, the authentication information is recalled, used, then erased.

Blocks and Block Qualifiers IAF 8.0 DML

5-51

/EXIT

/EXIT
Syntax
/EXIT=(dml_statement)

Description
This qualifier allows you to indicate the action IAF is to take if an end user presses the GM_EXIT key at an input, menu, pause, or yes/no block. By default, when an end user presses the GM_EXIT key at an input, menu, pause, or yes/no block, the form in which the given block resides exits. The /EXIT qualifier overrides the default behavior. For a list of DML statements that the /EXIT qualifier can indicate, refer to this manuals EXECUTING DML STATEMENTS VIA QUALIFIERS appendix.

Examples
/EXIT=(GOTO GET_DISC_PERCENTAGE) /EXIT=(CONTINUE ROLLBACK)

5-52

Blocks and Block Qualifiers IAF 8.0 DML

/EXIT_FORWARD

/EXIT_FORWARD
Syntax
/EXIT_FORWARD=(dml_statement)

Description
This qualifier allows you to indicate the action IAF is to take if an end user presses the GM_EXIT_FORWARD key at an input, menu, pause, or yes/no block. By default, when an end user presses the GM_EXIT_FORWARD key at an input menu, pause, or yes/no block, the form in which the block resides finishes its processing by using the default values of any remaining blocks that accept input as their input data instead of prompting the end user to enter the data. This default exit forward mode terminates when one of the following events takes place: The form exits. IAF prints an error message. IAF executes a subsequent block having the /EXIT_FORWARD qualifier, or a subsequent menu, pause, or yes/no block. IAF executes an input block having a /USING=REQUIRED or /USING=NOZERO qualifier, and the block has no data value yet. Note that if an input blocks /TARGET qualifier specifies a table field that is a primary identifier (PID) field, an implicit /USING=REQUIRED condition may exist for the block (for example; the block may require data.) IAF executes an input block that precedes the last executed input block. This condition can exist if the given form includes a /REPEAT or /TABLE form qualifier, or IAF executes a GOTO statement referencing an input block that precedes the current block. For a list of DML statements that the /EXIT_FORWARD qualifier can indicate, refer to this manuals Executing Dml Statements Via Qualifiers appendix. Note: The /EXIT_FORWARD qualifier only terminates the exit forward when used with the GOTO statement. Other non-branching statements such as PRINT or setting a variable have no affect on the program flow.

Blocks and Block Qualifiers IAF 8.0 DML

5-53

/EXIT_FORWARD

Note that when using the /EXIT_FORWARD qualifier with a menu or yes/no block, there are special requirements regarding the placement of the qualifier. Specifically, in a MENU_BLOCK statement, the /EXIT_FORWARD qualifier must precede any /ITEM and /ITEM_IF qualifiers that the MENU_BLOCK statement also includes. In a YESNO_BLOCK statement, the /EXIT_FORWARD qualifier must precede any /SUCCESS and /FAILURE qualifiers that the YESNO_BLOCK statement also includes.

Example
INPUT_BLOCK NAME /ROW=5 /COL=10 & /TARGET=CUSTOMERS(NAME) & /EXIT_FORWARD=(GOTO CONFIRM)

5-54

Blocks and Block Qualifiers IAF 8.0 DML

/FACILITY

/FACILITY
Syntax
/FACILITY /FACILITY=[[db-tag.][system-name:]]facility-name

Description
When the /FACILITY qualifier is present on a SIGNATURE_BLOCK, IAF checks to ensure that the username or usernames entered by the user have access to the specified facility. Both /FACILITY (with no facilityname) and /FACILITY=facility-name are accepted. In the former case, the specified facility is the currently executing facility. In other words, when no facility-name is specified, the effect is the same as if /FACILITY=%FACILITY is specified.

Blocks and Block Qualifiers IAF 8.0 DML

5-55

/FAILURE

/FAILURE
Syntax
/FAILURE=(dml-statement)

Description
This optional qualifier specifies a DML statement that IAF is to execute after the SIGNATURE_BLOCK completes when the specified usernames(s) and password(s) are determined to be invalid, either by the operating system or the optional validation routine. For a list of DML statements that the /FAILURE qualifier can execute, please refer to the appendix on Executing DML Statements Via Qualifiers in the IAF Data Manipulation Language Manual.

Example
/FAILURE=(GOTO INVALID_SIGNATURE)

5-56

Blocks and Block Qualifiers IAF 8.0 DML

/HEADING

/HEADING
Syntax
/HEADING=string_expression

Description
This qualifier allows you to indicate the column heading for an input block, output block, or yes/no block in a TABLE_EDIT form, or for an output block in a REPORT form. IAF left-justifies the heading over the given column, truncating the heading to the columns length. You can include a comma in the heading expression to force the heading portion before the comma to display on one line, and the heading portion after the comma to display on the next line. A heading can display over no more than two lines. By default, IAF generates a column heading when it executes the given form. You can center, left-justify, or right-justify each column heading over its related column via the /HEADING, /CHEADING, /LHEADING, or /RHEADING block qualifier. For details regarding the /CHEADING, /LHEADING and /RHEADING block qualifiers, refer to their descriptions in this section.

Example
/HEADING=Total,Value

Blocks and Block Qualifiers IAF 8.0 DML

5-57

/HEIGHT

/HEIGHT
Syntax
/HEIGHT=numeric_expression

Description
This qualifier allows you to define the height of an input, output, or menu blocks display area. However, this qualifiers exact behavior depends upon the type of block that specifies the qualifier.

For input blocks:

Appending the /HEIGHT qualifier to an INPUT_BLOCK statement is especially useful if: the statement also includes the /USING=MULTIPLE qualifier. The /USING=MULTIPLE block qualifier allows the end user to enter multiple values, including ranges and wildcards, via a table edit window. You can use the /HEIGHT qualifier to indicate the height of the table edit window. For details regarding the /USING qualifier and the MULTIPLE keyword, refer to this sections description of the /USING qualifier. the inputs target is a field having a DOCUMENTARY native datatype. The /HEIGHT qualifier also affects an input blocks background display height.

For output blocks:

You can append the /HEIGHT qualifier to an OUTPUT_BLOCK statement to cause the output blocks data to display over more than one

5-58

Blocks and Block Qualifiers IAF 8.0 DML

/HEIGHT

line. The following table describes the effect that this qualifier has depending on the value of its numeric expression. /HEIGHT Value 0 Effect A height of zero indicates that IAF is to use as many lines as necessary (limited only by reaching the end of the display window) to display the output data. IAF word wraps to prevent words from displaying over multiple lines. It is normally inadvisable to append the /HEIGHT=0 qualifier to an output block on a form that displays data. This is because IAF cannot recall the previous floating height of the display area when it clears data or attempts to display default data. Therefore it is possible for old data to remain displayed. One is the default height of all output blocks. IAF prints data on a single line of the specified length and truncates any remaining data as necessary. A height greater than one causes IAF to assume a fixed display height. IAF prints only the specified number of lines, and word wraps to prevent words from displaying over multiple lines.

n (any value greater than one)

IAF does not word wrap on segmented strings if the /LEN qualifier specifies an output block length that is smaller than or equal to the segment length.

Blocks and Block Qualifiers IAF 8.0 DML

5-59

/HEIGHT

For menu blocks:

You can append the /HEIGHT qualifier to a MENU_BLOCK statement to indicate the height of the given menu. If the number of items in the menu exceeds the value that the /HEIGHT qualifier specifies, the menu becomes a scrolling menu of the specified height. Indicating a value less than 2 via the /HEIGHT qualifier on a menu block causes IAF to ignore the /HEIGHT qualifier.

Example
Given the following variable:
#DATA=A quick brown fox jumped over the lazy dog

the following output blocks:

OUTPUT_BLOCK A /ROW=1 /COL=1 /LEN=10 /HEIGHT=1 /SOURCE=#DATA OUTPUT_BLOCK B /ROW=1 /COL=25 /LEN=10 /HEIGHT=3 /SOURCE=#DATA OUTPUT_BLOCK C /ROW=1 /COL=50 /LEN=10 /HEIGHT=0 /SOURCE=#DATA

produce the following output:

A quick br A quick brown fox jumped A quick brown fox jumped over the lazy dog

5-60

Blocks and Block Qualifiers IAF 8.0 DML

/INPUT_MASK

/INPUT_MASK
Syntax
/INPUT_MASK=mask_literal

Description
This qualifier allows you to indicate the format that an input block is to use for input data after it is entered. The given mask determines the inputs foreground length, and indicates the format IAF is to use for the input data immediately after the end user enters it. Input masks facilitate special formatting of data for inputs that handle currency, dates, times, etc. An input mask in the definition of a field that a /TARGET or /USING qualifier specifies overrides a mask that an /INPUT_MASK qualifier specifies. If the given INPUT_BLOCK statement includes the /LEN qualifier, it determines the inputs background display length. Otherwise, the input mask that the /INPUT_MASK qualifier specifies determines the inputs background display length. For details regarding input masks, refer to this manuals Input and Output Masks appendix.

Example
/INPUT_MASK=!-@@@@@0.@@

Blocks and Block Qualifiers IAF 8.0 DML

5-61

/ITEM

/ITEM
Syntax
/ITEM=tag_string_expression,description_string_expression,(dml_statement)

Description
This qualifier allows you to indicate a menu option that IAF is to include on the menu that the given menu block produces. A menu block must include at least one /ITEM or /ITEM_IF qualifier, and beyond that, may include any number of /ITEM and/or /ITEM_IF qualifiers. The /ITEM qualifier specifies the options tag (to facilitate selecting the option), a brief description of the option, and a DML statement that IAF is to execute if an end user selects the option on the menu. The /ITEM qualifier supersedes the /OPT qualifier. For a list of DML statements that the /ITEM qualifier can indicate, refer to this manuals Executing Dml Statements Via Qualifiers appendix. For details regarding the /ITEM_IF qualifier, refer to its description in this section.

Examples
MENU_BLOCK /ROW=10 /COL=35 & /ITEM=ADD,Add customers,(PERFORM ADD_CUSTS) & /ITEM=MODIFY,Modify customers,(PERFORM MODIFY_CUSTS) & /ITEM=DELETE,Delete customers,(PERFORM DELETE_CUSTS) & /ITEM=SHOW,Show customers,(PERFORM SHOW_CUSTS) & /ITEM=EXIT,Exit,(EXIT) MENU_BLOCK /ROW=2 /COL=4 & /ITEM=CREDITS,,(PERFORM LIST_CREDITS) & /ITEM=DEBITS,,(PERFORM LIST_DEBITS) & /ITEM=JOURNALS,,(PERFORM LIST_JOURNALS) & /ITEM=CONTINUE,,(EXIT)

5-62

Blocks and Block Qualifiers IAF 8.0 DML

/ITEM_IF

/ITEM_IF
Syntax
/ITEM_IF=(condition_expression),tag_string_expression, description_string_expression,(dml_statement)

Description
This qualifier allows you to indicate a menu option that IAF is to include on the menu that the given menu block produces if the condition expression that the qualifier specifies is true. A menu block must include at least one /ITEM or /ITEM_IF qualifier, and beyond that, may include any number of /ITEM and/or /ITEM_IF qualifiers. The /ITEM_IF qualifier specifies the condition expression IAF is to evaluate to determine if the option is to appear in the menu, the options tag (to facilitate selecting the option), a brief description of the option, and a DML statement that IAF is to execute if an end user selects the option on the menu. For a list of DML statements that the /ITEM_IF qualifier can indicate, refer to this manuals Executing DML Statements VIA Qualifiers appendix. For details regarding the /ITEM qualifier, refer to its description in this section.

Example
MENU_BLOCK CUSTOMER_MAINT_MENU /ROW=10 /COL=25 & /ITEM_IF=(#USER_ADDS=Y),ADD,Add New Customers,(PERFORM CUST_ADD) & /ITEM_IF=(#USER_MODS=Y),MOD,Modify Customers,(PERFORM CUST_MOD) & /ITEM_IF=(#USER_DELS=Y),DEL,Delete Customers,(PERFORM CUST_DEL) & /ITEM=SHOW,Show Customers,(PERFORM CUST_SHOW) & /ITEM=EXIT,Exit,(EXIT)

Blocks and Block Qualifiers IAF 8.0 DML

5-63

/LEN

/LEN
Syntax
/LEN=numeric_expression

Description
This qualifier allows you to hard-code an input or output blocks length. By default, IAF uses any relevant block qualifier specifications (/INPUT_MASK, /OUTPUT_MASK) and/or the definition of the given blocks target or source table field to derive a suitable block length. A block that does not have an explicit length is a floating block. The benefit of using floating blocks is that they enhance program maintainability because all field length and masking changes can be made centrally to the given table fields definition via the Data Definition Editor. For details regarding the Data Definition Editor, refer to the IAF System Reference Manual and the IAF guide that applies to your database engine. It is inadvisable to hard-code an input blocks length if the inputs target is a table field, or the input is to take on the characteristics of a table field due to the inclusion of the /USING=table_field block qualifier. However, you can use the /DISPLAY_LENGTH input block qualifier to indicate the size of the input blocks input area. Likewise, it is inadvisable to hardcode an output blocks length if the outputs source is a table field, or the output is to take on the characteristics of a table field due to the inclusion of the /USING=table_field block qualifier. The /LEN qualifier is especially useful for input blocks that include the /USING=MULTIPLE qualifier. The /USING=MULTIPLE qualifier allows an input block to accept multiple values per entry. By hard coding the blocks length, you can ensure that the block will be able to handle its input data. For details on the /USING qualifier, refer to its description in this section. IAF uses the following criteria at run-time to derive a suitable input or output block length if the given block does not include the /LEN qualifier: For an input block, IAF derives the blocks length from the /INPUT_MASK block qualifiers specification (if present.) For an

5-64

Blocks and Block Qualifiers IAF 8.0 DML

/LEN

output block, IAF derives the blocks length from the /OUTPUT_MASK block qualifiers specification (if present.) Otherwise, IAF uses the length in the definition of the table field that the /USING block qualifier specifies (if present) as the input block or output block length. For an input block, if no /USING qualifier is present, IAF uses the length in the definition of the table field that the /TARGET block qualifier specifies (if it specifies a field) as the block length. For an output block, if no /USING qualifier is present, IAF uses the length in the definition of the table field that the /SOURCE block qualifier specifies (if it specifies a field) as the block length. For an input block, if the /TARGET qualifier specifies a variable instead of a table field, IAF uses a default length of ten for the input block. For an output block, if the /SOURCE qualifier specifies a variable instead of a table field, IAF uses a block length that accommodates the output blocks data. IAF uses the following criteria to derive an input or output blocks length from a table fields definition (for example; when no mask block qualifier is present): For an input block, IAF derives the blocks length from the table fields input mask specification (if present.) For an output block, IAF derives the blocks length from the table fields output mask specification (if present.) For an input block, if the table fields definition does not include an input mask specification, IAF derives the blocks length from the input mask associated with the fields user-defined datatype (if any.) For an output block, if the table fields definition does not include an output mask specification, IAF derives the blocks length from the output mask associated with the fields user-defined datatype (if any.) Otherwise, IAF derives the blocks length from the table fields native datatype. IAF adds one to the length of numeric fields, such as WORD and LONGWORD fields, when determining a given blocks length.

Blocks and Block Qualifiers IAF 8.0 DML

5-65

/LEN

The following table lists native datatypes and their respective default display lengths. Native Datatype TEXT BYTE WORD LONGWORD QUADWORD UBYTE UWORD ULONGWORD D_FLOAT F_FLOAT G_FLOAT H_FLOAT DATE_TIME VARYING_STRING DOCUMENTARY NL NLO NR NRO NU NUMTEXT NZ PACKED YYMMDD Default Display Length field length 3 6 10 20 3 6 10 22 16 25 41 11 field length segment length based on dictionary field length based on dictionary field length based on dictionary field length based on dictionary field length based on dictionary field length based on dictionary field length based on dictionary field length based on dictionary field length 11

5-66

Blocks and Block Qualifiers IAF 8.0 DML

/LEN

Native Datatype YYYYMMDD 11

Default Display Length

To determine which of these datatypes are applicable when using IAF with a given database engine, refer to the IAF guide that applies to that database engine.

Examples
/LEN=10 /LEN=#FIELD_LENGTH

Blocks and Block Qualifiers IAF 8.0 DML

5-67

/LHEADING

/LHEADING
Syntax
/LHEADING=string_expression

Description
This qualifier allows you to indicate the column heading for an input block, output block, or yes/no block in a TABLE_EDIT form, or for an output block in a REPORT form. IAF left-justifies the heading over the given column, without truncating the heading to the columns length (for example, the heading can extend over several columns.) You can include a comma in the heading expression to force the heading portion before the comma to display on one line, and the heading portion after the comma to display on the next line. A heading can display over no more than two lines. By default, IAF generates a column heading when it executes the given form. You can center, left-justify, or right-justify each column heading over its related column via the /HEADING, /CHEADING, /LHEADING, or /RHEADING block qualifier. For details regarding the /HEADING, /CHEADING and /RHEADING block qualifiers, refer to their descriptions in this section.

Example
/LHEADING=Customer Name

5-68

Blocks and Block Qualifiers IAF 8.0 DML

/LOV

/LOV
Syntax
/LOV=table_name(field_name[,field_name[,...]])

Description
This qualifier allows you to indicate the field(s) to include in the list of values that IAF displays when an end user presses the GM_LIST_OF_VALUES key on the input block that specifies this qualifier. A list of values (LOV) is a list of valid responses for a given input. IAF displays the list in a window. You can use the LOV mechanism to override a default list that IAF would otherwise generate, or to create a list where IAF would normally not generate one. IAF uses implicit and explicit domains (joins between tables) to generate LOVs. IAF displays values from the specified table field(s.) After an end user selects an entry from the list, IAF places in the input field the data from the first field that the /LOV qualifier specifies. To completely disable the list of values for an input block, you can use the /OPTIONS=NOLOV_ALLOWED block qualifier. For details regarding the /OPTIONS qualifier, refer to its description in this section.

Example
/LOV=CUSTOMERS(CUSTOMER_ID,CUSTOMER_NAME)

Blocks and Block Qualifiers IAF 8.0 DML

5-69

/LOV_AUTO_SELECT

/LOV_AUTO_SELECT
Syntax
/LOV_AUTO_SELECT

Description
This qualifier causes the list of values mechanism to be active whenever IAF executes the input block that specifies this qualifier. This means that the end user will always be selecting from a list of values and IAF will not allow the end user to enter a value by typing it and pressing GM_CR.

Example
INPUT_BLOCK EMPLOYEE /ROW=10 /COL=35 & /LOV=EMPLOYEES(EMPLOYEE_ID,LAST_NAME) /LOV_AUTO_SELECT & /PROMPT=(FIELD_PROMPT(EMPLOYEE_ID)) /TARGET=DEPARTMENTS(EMPLOYEE_ID)

5-70

Blocks and Block Qualifiers IAF 8.0 DML

/LOV_COL

/LOV_COL
Syntax
/LOV_COL=numeric_expression

Description
This qualifier allows you to indicate the screen column in which to display the first column of the LOV window. The numeric expression must be greater than or equal to 1, and less than or equal to the current screen width minus 40. By default, IAF displays the first column of the LOV window in the current input block column if it is less than or equal to the screen width minus 40, or in the column that is 40 columns less than the screen width, otherwise. The length of the field(s) that the /LOV qualifier specifies determines the LOV windows width.

Examples
/LOV_COL=24 /LOV_COL=#CUST_LIST_COL

Blocks and Block Qualifiers IAF 8.0 DML

5-71

/LOV_DATA

/LOV_DATA
Syntax
/LOV_DATA=field_name

Description
This qualifier allows you to indicate the field whose data the LOV mechanism is to place in the input blocks target field. By default, the LOV mechanism places in the target field data from the first field that the /LOV qualifier specifies. You can use this qualifier to indicate an alternate field from which IAF is to extract data (for example; a field that the /LOV qualifier does not indicate.) For information on preventing the LOV mechanism from placing data in the inputs target field, refer to this sections description of the /NOLOV_DATA block qualifier.

Example
INPUT_BLOCK EMPLOYEE /ROW=10 /COL=35 & /LOV=EMPLOYEES(LAST_NAME, FIRST_NAME) & /LOV_DATA=EMPLOYEE_ID & /PROMPT=(FIELD_PROMPT(EMPLOYEE_ID)) & /TARGET=DEPARTMENTS(EMPLOYEE_ID)

5-72

Blocks and Block Qualifiers IAF 8.0 DML

/LOV_FIRST

/LOV_FIRST
Syntax
/LOV_FIRST=nnnn

Description
This qualifier allows you to indicate the number of records to display in the LOV. The given value, which must be a positive integer, causes IAF to include in the LOV only the first nnnn records that match any search criteria that the end user entered.

Example
/LOV_FIRST=20

Blocks and Block Qualifiers IAF 8.0 DML

5-73

/LOV_HEIGHT

/LOV_HEIGHT
Syntax
/LOV_HEIGHT=numeric_expression

Description
This qualifier allows you to indicate the height of the LOV window. By default, IAF uses a default height of ten for LOV windows, and places heading information in the first three lines of the window. The length of the field(s) that the /LOV qualifier specifies determines the width of the LOV window.

Example
/LOV_HEIGHT=13 /LOV_HEIGHT=#LIST_HEIGHT

5-74

Blocks and Block Qualifiers IAF 8.0 DML

/LOV_NOHEADING

/LOV_NOHEADING
Syntax
/LOV_NOHEADING

Description
This qualifier indicates that no heading information is to appear above the column(s) in the LOV window. By default, IAF places a heading above each column in LOV window. Example
INPUT_BLOCK EMPLOYEE /ROW=10 /COL=35 & /LOV=EMPLOYEES(EMPLOYEE_ID) & /LOV_NOHEADING & /TITLE=Emp. ID & /PROMPT=(FIELD_PROMPT(EMPLOYEE_ID)) & /TARGET=DEPARTMENTS(EMPLOYEE_ID)

Blocks and Block Qualifiers IAF 8.0 DML

5-75

/LOV_NOSEARCH

/LOV_NOSEARCH
Syntax
/LOV_NOSEARCH

Description
This qualifier indicates that the LOV window is not to accept search criteria from the end user. It is intended for use in situations in which entire record set is so small that using additional search filters would be unnecessary.

Example
INPUT_BLOCK TYPE /ROW=10 /COL=35 & /LOV=MEMBERSHIP_TYPES(MEMBERSHIP_TYPE) & /LOV=NOSEARCH & /PROMPT(FIELD_PROMPT(MEMBERSHIP_TYPE)) & /TARGET=MEMBERS(MEMBERSHIP_TYPE)

5-76

Blocks and Block Qualifiers IAF 8.0 DML

/LOV_REDUCED_TO

/LOV_REDUCED_TO
Syntax
/LOV_REDUCED_TO=[-]field_name[,[-]field_name[,...]]

or
/LOV_REDUCED_TO=[-]#variable_name[,[-]#variable_name[,...]]

Description
This qualifier allows you to indicate the field(s) for which the LOV records are to contain unique values (for example; the given value or combination of values is not to repeat in the listing.) Field specifications for the /LOV_REDUCED_TO qualifier can be field names or the names of variables that equate to field names. To produce a meaningful LOV, the input block that includes this qualifier must also include a /LOV_SORTED_BY qualifier Indicating the same fields that this qualifier does. If the /LOV_SORTED_BY qualifier specifies a descending sort order for a given field, this qualifier should do the same by preceding the field specification by a minus sign (-.)

Example
INPUT_BLOCK REP_ID /ROW=10 /COL=35 & /LOV=ORDERS(REP_ID, CUSTOMER_ID) & /LOV_SORTED_BY=REP_ID, CUSTOMER_ID & /LOV_REDUCED_TO=REP_ID, CUSTOMER_ID & /PROMPT=(FIELD_PROMPT(REP_ID)) & /TARGET=BONUSES(REP_ID)

Blocks and Block Qualifiers IAF 8.0 DML

5-77

/LOV_ROW

/LOV_ROW
Syntax
/LOV_ROW=numeric_expression

Description
This qualifier allows you to indicate the screen row on which IAF is to display the first line of the LOV window. By default, IAF displays the first line of the LOV window on the same row as the current input block.

Examples
/LOV_ROW=10 /LOV_ROW=((#FORM_HEIGHT-#LOV_HEIGHT) / 2)

5-78

Blocks and Block Qualifiers IAF 8.0 DML

/LOV_SECONDARY

/LOV_SECONDARY
Syntax
/LOV_SECONDARY

Description
This qualifier causes IAF to create a secondary stream on which to perform the LOV for the table that the /LOV qualifier specifies. Normally, IAF performs the LOV on the given tables primary stream. Performing the LOV on a secondary stream ensures that the primary streams data will not be destroyed when IAF executes a recursive list of values. You cannot extract other data from a record found on the secondary stream after selecting the record from the LOV because IAF ends the secondary stream upon exiting the LOV window.

Blocks and Block Qualifiers IAF 8.0 DML

5-79

/LOV_SELECTION

/LOV_SELECTION
Syntax
/LOV_SELECTION=boolean_expression

Description
This qualifier allows you to indicate a Boolean selection statement indicating the record selection IAF is to use when selecting records that are to appear in the LOV. A Boolean selection statement is a logical combination of some or all /LOV_WITH clauses that the given block specifies. IAF assigns each clause an identifier of A-Z, where A represents the first /LOV_WITH clause, B represents the second /LOV_WITH clause, and so on. A Boolean selection statement can use these identifiers to refer to /LOV_WITH clauses. Alternatively, a Boolean selection statement can use identifiers consisting of an asterisk (*) followed by a number, where *1 represents the first /LOV_WITH clause, *2 represents the second /LOV_WITH clause, and so on. The advantage of using identifiers of the latter type is that they make it possible to refer to more than 26 /LOV_WITH clauses (the limit that the alphabet imposes.) Note that a Boolean selection statement can use identifiers of all one type or a combination of both types. Also note that a Boolean selection statement may refer to a given /LOV_WITH clause once, more than once, or not at all.

5-80

Blocks and Block Qualifiers IAF 8.0 DML

/LOV_SELECTION

Operator Precedence
The following table lists, in order of precedence, the Boolean operators that are available for use with the /LOV_SELECTION qualifier. By using parentheses it is possible to change the order in which IAF evaluates a given selection statement. Operator NOT Example A OR NOT B Selection Behavior This example specifies that /LOV_WITH clause A must be true or /LOV_WITH clause B must be false for a given record selection to take place. This example specifies that /LOV_WITH clause A must be true and /LOV_WITH clause B must be false for a given record selection to take place. This example specifies that /LOV_WITH clauses A and B must be true for a given record selection to take place. This example specifies that /LOV_WITH clause A or /WITH clause B must be true for a given record selection to take place.

A AND NOT B

AND

A AND B

OR

A OR B

Blocks and Block Qualifiers IAF 8.0 DML

5-81

In place of a Boolean selection statement, the /LOV_SELECTION qualifier can indicate one of the keywords that the following table lists. Keyword ALL Selection Behavior This keyword specifies that all /LOV_WITH clauses must be true for a given record selection to take place. This is the default behavior if no /LOV_SELECTION qualifier is present. This keyword specifies that at least one /LOV_WITH clause must be true for a given record selection to take place.

ANY

Examples
Given the following /LOV_WITH clauses:
/LOV_WITH=PARTS_CODE MATCHING S* & /LOV_WITH=PARTS_CODE MATCHING X* & /LOV_WITH=QUANTITY > 50

The following /LOV_SELECTION qualifier is valid:

/LOV_SELECTION=(A OR B) AND C

This /LOV_SELECTION qualifier causes the LOV to include only records for parts having a part code that begins with S or X of which at least 50 are available.
/LOV_SELECTION=ANY

This /LOV_SELECTION qualifier causes the LOV to include only records for parts having a part code that begins with S or X, and/or of which at least 50 are available.

5-82

Blocks and Block Qualifiers IAF 8.0 DML

/LOV_SORTED_BY

/LOV_SORTED_BY
Syntax
/LOV_SORTED_BY=[-]field_name[,[-]field_name[,...]]

or
/LOV_SORTED_BY=[-]#variable_name[,[-]#variable_name[,...]]

Description
This qualifier allows you to indicate the order in which IAF is to sort the records that are to appear in the LOV. If you indicate multiple fields via this qualifier, indicate them in descending significance order (for example; sort by state then city, instead of city then state.) Field specifications for the /LOV_SORTED_BY qualifier can be field names or the names of variables that equate to field names. The default sort order for each field is ascending. To indicate a descending sort order for a field, precede its specification by a minus sign (-.) Note that the field(s) that the /LOV_SORTED_BY qualifier specifies must match the field(s) that the /LOV_REDUCED_TO qualifier specifies, if present, to produce a meaningful LOV. For details on the /LOV_REDUCED_TO block qualifier, refer to its description in this chapter.

Example
INPUT_BLOCK REP_ID /ROW=10 /COL=35 & /LOV=ORDERS(REP_ID, CUSTOMER_ID) & /LOV_SORTED_BY=REP_ID, CUSTOMER_ID & /LOV_REDUCED_TO=REP_ID, CUSTOMER_ID & /PROMPT=(FIELD_PROMPT(REP_ID)) & /TARGET=BONUSES(REP_ID)

Blocks and Block Qualifiers IAF 8.0 DML

5-83

/LOV_WIDTH

/LOV_WIDTH
Syntax
/LOV_WIDTH=numeric_expression

Description
This qualifier allows you to indicate the width of the LOV window. IAF wraps to the next and subsequent lines any field(s) that the window cannot accommodate. This qualifier facilitates preventing the LOV window from shifting position and/or changing its display width (for example; from 80-column mode to 132- column mode) if the LOV windows width is not sufficient to accommodate the field(s) that the /LOV qualifier specifies.

Example
/LOV_WIDTH=50

5-84

Blocks and Block Qualifiers IAF 8.0 DML

/LOV_WITH

/LOV_WITH
Syntax
/LOV_WITH=field_name operator value_expression

Description
This qualifier allows you to indicate clauses to qualify records and thereby, create record subsets. IAF imposes no limit on the number of /LOV_WITH qualifiers a given block may include. IAF assigns unique identifiers to each /LOV_WITH clause. You can use these identifiers to form a Boolean selection statement via the /LOV_SELECTION block qualifier. For details regarding the /LOV_SELECTION qualifier, refer to its description in this chapter. Following are descriptions of the components that comprise a /LOV_WITH qualifiers specification:

field_name
This is the name of the field whose data IAF is to examine as part of the LOV record selection process.

operator
This is an indicator of the mathematical, logical, or textual operation that IAF is to perform on the given data. The following table lists and describes the relational operators that are valid for use with the /LOV_WITH qualifier. You can precede the last five operators by the NOT operator to reverse their effect. Operator = <> <= Description Determines if the value of the field on its left is equal to the value of the expression on its right. Determines if the value of the field on its left is unequal to the value of the expression on its right. Determines if the value of the field on its left is less than or equal to the value of the expression on its right.

Blocks and Block Qualifiers IAF 8.0 DML

5-85

/LOV_WITH

Operator >=

Description Determines if the value of the field on its left is greater than or equal to the value of the expression on its right. Determines if the value of the field on its left is less than the value of the expression on its right. Determines if the value of the field on its left is greater than the value of the expression on its right. Determines if the data in the field on its left is among the list of values and/or ranges on its right. This operator is a wildcard operator. Therefore, certain database engines may not support its use on non-text fields. To determine if a particular engine supports using this operator on non-text fields, refer to the IAF guide that applies to that database engine. Determines if the field on its left contains the data on its right. This operator is case-insensitive. Determines if the data in the field on its left matches the wildcard pattern on its right. The given wildcard pattern may include the wildcard characters * and %, where * represents zero or more unknown characters, and % represents a single unknown character. This operator is a wildcard operator. Therefore, certain database engines may not support its use on non-text fields. To determine if a particular engine supports using this operator on non-text fields, refer to the IAF guide that applies to that database engine. This operator is case-sensitive. Determines if the value in the field on its left is the missing value. This operator does not require an operand on its right. For details regarding missing values, refer to the IAF Users Guide. To determine if a particular database engine supports missing values, refer to the IAF guide that applies to that database engine.

< > AMONG

CONTAINING MATCHING

MISSING

5-86

Blocks and Block Qualifiers IAF 8.0 DML

/LOV_WITH

Operator STARTING WITH

Description Determines if the data in the field on its left starts with the value of the expression on its right. This operator is a wildcard operator. Therefore, certain database engines may not support its use on nontext fields. To determine if a particular engine supports using this operator on non- text fields, refer to the IAF guide that applies to that database engine. This operator is case- sensitive.

value_expression
This is any valid DML expression, such as a literal, table field, or argument.

Examples
INPUT_BLOCK PART_CODE /ROW=10 /COL=35 & /LOV=PARTS(PART_CODE) & /LOV_WITH=PARTS_CODE MATCHING S* & /LOV_WITH=PARTS_CODE MATCHING X* & /LOV_WITH=QUANTITY > 50 & /LOV_SELECTION=(A OR B) AND C & /PROMPT=(FIELD_PROMPT(PART_CODE)) & /TARGET=ORDER_DETAILS(PART_CODE)

Blocks and Block Qualifiers IAF 8.0 DML

5-87

/NEW

/NEW
Syntax
/NEW

Description
This qualifier causes IAF to reverse any domain validation that it performs. Therefore, the domain validation succeeds if no record containing the given value exists in the domain table. If the domain validation fails ( a record containing the given value exists in the domain table), IAF displays an error message. This qualifier allows you to prevent the entry of a new record with the given field value if such a record already exists. When using the /NEW qualifier, the target table and the domain table must be the same table. Therefore, Indicating both the /DOMAIN qualifier and the /NEW qualifier causes IAF to ignore the /NEW qualifier. For details regarding domains, refer to this sections description of the /DOMAIN qualifier and the IAF Users Guide.

Using /NEW with /PROTECT

Using the /NEW and /PROTECT qualifiers together is useful in a situation in which a table has two domains, with unique constraints, that IAF is to validate. To illustrate the effect of using these two qualifiers together, assume that your form has the following input blocks:
INPUT_BLOCK PART_ID /ROW=10 /COL=25 & /TARGET=PARTS(PART_ID) & /NEW INPUT_BLOCK BIN_NUMBER /ROW=12 /COL=25 & /TARGET=PARTS(BIN_NUMBER) & /DOMAIN=PARTS & /NEW INPUT_BLOCK DESCRIPTION /ROW=14 /COL=25 & /TARGET=PARTS(DESCRIPTION)

5-88

Blocks and Block Qualifiers IAF 8.0 DML

/NEW

Where PART_ID is the PID for the PARTS table, and BIN_NUMBER is a secondary unique index for the PARTS table (parts with a given ID can reside in only one bin, and a given bin can contain parts having only a given ID.) If an end user enters part ID HD0238 and bin number 24, IAF writes the record to the PARTS table if no PARTS table record contains either of these values. However, attempts to modify the record subsequently (for example; to modify the description) will not be successful because the end user will not be able to get past the BIN_NUMBER input block. The end user will want to press GM_CR to preserve the records bin number, but IAF will not allow this due to the /NEW qualifier. Using /PROTECT with /NEW on the BIN_NUMBER input block will rectify this situation, by allowing the end user to modify the value of the secondary unique index. IAF recognizes the combined use of /PROTECT and /NEW as a special case requiring this treatment.

Example
INPUT_BLOCK NEW_ORDER_NUMBER /ROW=10 /COL=20 & /TARGET=SALES_ORDERS(ORDER_NUMBER) & /DOMAIN=SALES_ORDERS & /NEW

Blocks and Block Qualifiers IAF 8.0 DML

5-89

/NOAUDIT

/NOAUDIT
Syntax
/NOAUDIT

Description
This optional qualifier specifies that no audit record is to be written. An audit record is always written unless the /NOAUDIT qualifier is specified. It is not permitted to specify both the /AUDIT and the /NOAUDIT qualifiers in the same SIGNATURE_BLOCK.

Example
/NOAUDIT

5-90

Blocks and Block Qualifiers IAF 8.0 DML

/NOCLEAR_BUFFER

/NOCLEAR_BUFFER
Syntax
/NOCLEAR_BUFFER

Description
This qualifier indicates that IAF is not to clear the user buffer when a given domain validation fails. By default, IAF blanks all current user buffer entries for all domain table fields, except PID fields, if the look-up on the domain table fails. Indicating the /NOCLEAR_BUFFER qualifier causes IAF to leave the data from the domain table fields in the user buffer, even if the validation fails. For details regarding user buffers and domains, refer to the IAF Users Guide.

Blocks and Block Qualifiers IAF 8.0 DML

5-91

/NODOMAIN

/NODOMAIN
Syntax
/NODOMAIN

Description
This qualifier indicates that IAF is not to validate any implicit or explicit domains for the given input block. For details regarding domains, refer to the IAF Users Guide.

5-92

Blocks and Block Qualifiers IAF 8.0 DML

/NOLOV_DATA

/NOLOV_DATA
Syntax
/NOLOV_DATA

Description
This qualifier allows you to prevent the LOV mechanism from placing data in the given input blocks target field. It facilitates displaying a list of existing records for an end user attempting to add a new record. The end user can refer to the list to determine values that are not valid to enter because they already exist.

Example
INPUT_BLOCK NEW_ORDER_NUMBER /ROW=10 /COL=20 & /TARGET=SALES_ORDERS(ORDER_NUMBER) & /DOMAIN=SALES_ORDERS & /NEW & /LOV=SALES_ORDERS(ORDER_NUMBER) & /LOV_SORTED_BY=ORDER_NUMBER & /NOLOV_DATA & /PROMPT=(FIELD_PROMPT(ORDER_NUMBER))

/NOHEADING
Syntax
/NOHEADING

Description
This qualifier prevents IAF from displaying the given output blocks default column heading. This qualifier is applicable only to output blocks on REPORT forms.

Blocks and Block Qualifiers IAF 8.0 DML

5-93

/NOREPEAT

/NOREPEAT
Syntax
/NOREPEAT

Description
This qualifier prevents IAF from returning control to the given menu block after executing the DML statement associated with the selected menu option. By default, IAF repeats execution of the menu block to enable the end user to select another option on the menu. The /NOREPEAT qualifier causes IAF to allow the end user to make a single selection from the menu, execute the DML statement associated with the option that the end user selects, and then transfer control to the next block on the form.

/NOUNDERLINES
Syntax
/NOUNDERLINES

Description
This qualifier prevents the default line of dashes from displaying/printing below the given blocks heading (if any), and is applicable to input, output, and yes/no blocks on TABLE_EDIT forms, and output blocks on REPORT forms.

5-94

Blocks and Block Qualifiers IAF 8.0 DML

/OPT

/OPT
Syntax
/OPT=tag[;description],dml_statement

Description
This qualifier allows you to indicate the menu options IAF is to include on the menu that the given menu block produces, and is functionally identical to the /ITEM qualifier. The /ITEM qualifier supersedes the /OPT qualifier. Therefore it is advisable to use the /ITEM qualifier instead of the /OPT qualifier.

Blocks and Block Qualifiers IAF 8.0 DML

5-95

/OPTIONS

/OPTIONS
Syntax
/OPTIONS=domain-options

Description
This optional qualifier permits you to specify domain-locking options. The available domain locking options are DOMAIN_LOCK_NONE and DOMAIN_LOCK_WRITE. Do not enclose the domain locking options in parenthesis. DOMAIN_LOCK_NONE specifies that any domain look-ups for the DOMAIN_LOCK_WRITE specifies that IAF should place write locks on records it finds via domain lookups. For further details regarding this qualifier, please refer to the entry for the /OPTIONS qualifier in the Blocks and Block Qualifiers chapter in the IAF Data Manipulation Language Manual. For details regarding locks and domains, please refer to the IAF Users Guide. Example /OPTIONS=DOMAIN_LOCK_NONE

5-96

Blocks and Block Qualifiers IAF 8.0 DML

/OUTPUT_MASK

/OUTPUT_MASK
Syntax
/OUTPUT_MASK=mask_literal

Description
This qualifier allows you to indicate the format an output block is to use to display its source data. An output mask in the definition of a field that a /SOURCE or /USING qualifier specifies overrides a mask that an /OUTPUT_MASK qualifier specifies. When displaying or printing source text data, IAF substitutes the data on a character-by-character basis for a series of predefined token characters in the given output mask. When displaying or printing source dates, IAF substitutes applicable parts of the data for predefined date tokens in the given output mask. Source dates must be in the standard format DDMon-YYYY to be masked. IAF rounds numeric data when formatting it for a masked output (values less than 0.5 round down, values greater than or equal to 0.5 round up.) For details regarding output masks, refer to this manuals Input and Output Masks appendix.

Examples
/OUTPUT_MASK=!-@@@@@@0.@@CR /OUTPUT_MASK=Department code: @@@@ /OUTPUT_MASK=!-@@\Lm\@@@@

Blocks and Block Qualifiers IAF 8.0 DML

5-97

/PDF

/PDF
Syntax
/PDF=(option=value[, option=value[, . . .]])

Description
This qualifier applies to OUTPUT_BLOCKs in REPORT forms. The PDF qualifier has several options. The entire option list has a whole should be enclosed in parenthesis. Please refer to the /PDF qualifier for REPORT Forms and the "PDF Reports and PDF File Production" section of this document for more information concerning IAF and PDF production.

Options
FONT=font-text This option specifies the font to be used for the OUTPUT_BLOCK in the PDF document. More information about fonts can be found under the FONTNAME option of the /PDF qualifier for the REPORT form. See also the examples at the end of this section. BORDER=border-text This option determines how the OUTPUT_BLOCK border and background is rendered. The border-text should be enclosed in parenthesis, and should be a comma separated list of options from the following list: FILL=color,STROKE=color,LEFT,RIGHT,TOP,BOTTOM,NONE,EXPA ND. RENDER=render-option-list This option specified how the OUTPUT_BLOCK text is rendered. See the description of the RENDER option for the /PDF qualifier of the REPORT form. COLOR=color-option-list See the description of the COLOR option for the /PDF qualifier of the REPORT form.

5-98

Blocks and Block Qualifiers IAF 8.0 DML

/PDF

Examples
This first example shows one way to use a different font for each column:
REPORT_FORM PDF_FONTS_EXAMPLE & /READ_ONLY & /WIDTH=69 & /OUTPUT="c:\Reports\Movies_Font3_Sizes" & /TABLE=Movies & /LHEADING=(MASK("!DD-!SM-!LY !HH:!MI", %REPORT_DATE )) & /RHEADING=(MASK("Page !-@@@", %PAGE) & " of {%Page}") & /PDF=(FONTS=("normal=Courier:12,H12=Helvetica:12,T12=TimesRoman:12"), & MARGINS="Top=.5,Bottom=.5,Left=.5,Right=.5", & PAGESIZE="Letter,Portrait", & TITLE="Font Sizes", & VIEWERPREFERENCES="DisplayDocTitle" ) ! Helvetica 12 point OUTPUT_BLOCK Movie_ID /SOURCE=(Movies(Movie_ID)) /PDF=(FONT="H12") ! Times-Roman 12 point OUTPUT_BLOCK Movie_Title /SOURCE=(Movies(Movie_Title)) /PDF=(FONT="T12") ! Courier 12 point OUTPUT_BLOCK Price /SOURCE=(Movies(Price)) /TOTAL ! Courier-Bold 12 point

OUTPUT_BLOCK Times_Rented /SOURCE=(Movies(Times_Rented)) /TOTAL /ATTRIBUTES=BOLD ! Courier-BoldOblique 12 point

OUTPUT_BLOCK Movie_Type /SOURCE=(Movies(Movie_Type)) /ATTRIBUTES= BOLD,ITALIC END_FORM

The following example produces a report with dark blue text on alternating rows of white and lavender background, resembling computer line printer paper.
REPORT_FORM PDF_Fancy_Stripes & /READ_ONLY & /WIDTH=69 & /OUTPUT=("c:\reports\MoviesFancyStripes") &

Blocks and Block Qualifiers IAF 8.0 DML

5-99

/PDF

/TABLE=Movies & /LHEADING=(MASK("!DD-!SM-!LY !HH:!MI", %REPORT_DATE )) & /RHEADING=(MASK("Page !-@@@", %PAGE) & " of {%PAGE}") & /PDF=(BACKGROUND="color=white", & FONTNAME="Helvetica", & MARGINS="Top=.5,Bottom=.5,Left=.5,Right=.5", & PAGESIZE="Letter,Portrait", & TITLE="Fancy Movies Report", & VIEWERPREFERENCES="DisplayDocTitle" )

IF (%ROW_NUMBER AND_B 1) #b = "FILL=White, STROKE=DarkBlue, EXPAND" #r = "FILL=DarkBlue" ELSE #b = "FILL=lavender, STROKE=DarkBlue, EXPAND" #r = "FILL=DarkBlue" END_IF OUTPUT_BLOCK Movie_ID & /SOURCE=(Movies(Movie_ID)) & /PDF=(BORDER=(#b & ",NONE"), RENDER=#r)

OUTPUT_BLOCK Movie_Title & /SOURCE=(Movies(Movie_Title)) & /PDF=(BORDER=(#b & ",LEFT"), RENDER=#r)

OUTPUT_BLOCK Price & /SOURCE=(Movies(Price)) & /PDF=(BORDER=(#b & ",LEFT"), RENDER=#r) & /TOTAL END_FORM

5-100

Blocks and Block Qualifiers IAF 8.0 DML

/PROMPT

/PROMPT
Syntax
/PROMPT=dml_expression

Description
This qualifiers characteristics depend on the block statement that specifies it. In general, this qualifier allows you to indicate the screen prompt that is to display to the left of the given blocks display area. By default, IAF places two spaces between the end of the given prompt and the beginning of the display area. Specifically, the /PROMPT qualifiers behavior is a follows: For an input block, this qualifier allows you to indicate the prompt that indicates the information that the end user is to enter for the input. For an output block, this qualifier allows you to indicate the prompt that describes the output data. For a pause block, this qualifier allows you override the default system prompt of Press (RETURN) to continue.... For a yes/no block, this qualifier allows you to indicate the question for which the end user is to enter a yes or no response. For an item block, this qualifier allows you to indicate the tag for the menu option that the block describes. A tag is a handle that facilitates the selection of a given menu option. The /PROMPT qualifier allows you to override the tag specified for a given option via the System Definition Editor. An item blocks /COL qualifier specifies the column position in which the first letter of the item tag is to display. The /TAG qualifiers behavior is identical to the /PROMPT qualifiers behavior when appended to an item block. Therefore, you can append the /TAG qualifier to an item block in place of the /PROMPT qualifier. However, if you append a /TAG qualifier to an item block, and subsequently load the given menu into the forms editor, the forms editor replaces the /TAG qualifier with the /PROMPT qualifier. Upon saving the menu and exiting the forms editor, you can use any text editor to see the change in the code. Although the codes appearance changes, its behavior remains the same.

Blocks and Block Qualifiers IAF 8.0 DML

5-101

/PROMPT

For an input or output block in a TABLE_EDIT form, you can use the FIELD_PROMPT built-in function to obtain the prompt from the given fields definition at run-time. To enhance program data independence, use this built-in function instead of hard-coding the prompt into the DML program whenever possible. For details regarding FIELD_PROMPT and other built-in functions, refer to this manuals Built-in Functions chapter.

Examples
OUTPUT_BLOCK CUST_ID /ROW=2 /COL=10 & /SOURCE=SALES_ORDERS(CUSTOMER_ID) & /PROMPT=FIELD_PROMPT(CUSTOMER_ID) ITEM_BLOCK ORDER_ENTRY /ROW=2 /COL=10 & /FACILITY=ORDER_ENTRY & /PROMPT=ORDERS PAUSE_BLOCK /ROW=10 /COL=10 & /PROMPT=Press F13 to continue YESNO_BLOCK CONFIRM /ROW=10 /COL=15 & /PROMPT=Add this record? & /SUCCESS=(ADD TO SALES_ORDERS) /INPUT_BLOCK CUST_ID /ROW=2 /COL=10 & /TARGET=SALES_ORDERS(CUSTOMER_ID) & /PROMPT=(#NEW_PROMPT & :)

5-102

Blocks and Block Qualifiers IAF 8.0 DML

/PROTECT

/PROTECT
Syntax
/PROTECT

Description
This qualifier causes IAF to perform the given input blocks domain validation on a secondary stream, and to preserve any data in the user buffer associated with the primary stream, regardless of the validations result. By default, IAF performs domain validations on the domain tables primary stream, thereby overwriting any previous record in the user buffer associated with the stream. IAF uses the GEM_PROTECT stream to retrieve records it finds during a domain validation on an input block Indicating the /PROTECT qualifier. Records in the streams user buffer are available until the next input block with a /PROTECT qualifier executes, or the form exits. To access data in the user buffer associated with the GEM_PROTECT stream, use the format GEM_PROTECT:table_name(field_name), where table_name is the name of the domain table, and field_name is the name of the field you wish to access. For details on primary and secondary streams, refer to the IAF Users Guide.

Using /PROTECT with /NEW

Using the /NEW and /PROTECT qualifiers together is useful in a situation in which a table has two domains, with unique constraints, that IAF is to validate. To illustrate the effect of using these two qualifiers together, assume that your form has the input blocks on the following page.
INPUT_BLOCK PART_ID /ROW=10 /COL=25 & /TARGET=PARTS(PART_ID) /NEW INPUT_BLOCK BIN_NUMBER /ROW=12 /COL=25 & /TARGET=PARTS(BIN_NUMBER) & /DOMAIN=PARTS /NEW INPUT_BLOCK DESCRIPTION /ROW=14 /COL=25 & /TARGET=PARTS(DESCRIPTION)

where PART_ID is the PID for the PARTS table, and BIN_NUMBER is a secondary unique index for the PARTS table (for example; parts with a given ID can reside in only one bin, and a given bin can contain parts having only a given ID.) If an end user enters part ID HD0238 and bin number 24, IAF writes the record to the PARTS table if no PARTS table
Blocks and Block Qualifiers IAF 8.0 DML 5-103

/PROTECT

record contains either of these values. However, attempts to modify the record subsequently (for example; to modify the description) will not be successful because the end user will not be able to get past the BIN_NUMBER input block. The end user will want to press GM_CR to preserve the records bin number, but IAF will not allow this due to the /NEW qualifier. Using /PROTECT with /NEW on the BIN_NUMBER input block will rectify this situation, by allowing the end user to modify the value of the secondary unique index. IAF recognizes the combined use of /PROTECT and /NEW as a special case requiring this treatment.

Example
INPUT_BLOCK NEW_ORDER_NUMBER /ROW=10 /COL=20 & /TARGET=SALES_ORDERS(ORDER_NUMBER) /DOMAIN=SALES_ORDERS & /PROTECT

5-104

Blocks and Block Qualifiers IAF 8.0 DML

/PURPOSE

/PURPOSE
Syntax
/PURPOSE=purpose

Description
This optional qualifier specifies the purpose of the SIGNATURE_BLOCK. The value is recorded in the audit record, if any, that is written. Purpose can be both a source and a target. It can be a quoted string literal, a function, a special variable, or any variable or table-field that is acceptable as a target of an input block. If you wish the purpose to be used solely as a source (to provide a default for the user input) and not to be set as a target, enclose the variable or table field in parentheses. IAF will then treat the variable or table field as a read-only expression. If purpose is defined as a target table-field, then any List-of-Values (/LOV) qualifier specified in the SIGNATURE_BLOCK will take effect. The /LOV and related qualifiers apply only to this input field but will be ignored if purpose specifies anything other a writable table-field.

Example
/PURPOSE=#sig_purpose /PURPOSE=(#readonly_sig_purpose) /PURPOSE=signatures(valid_purpose)

Blocks and Block Qualifiers IAF 8.0 DML

5-105

/RECALL
The /RECALL qualifier is used to recall the validated authentication information as saved by a prior SIGNATURE_BLOCK or SIGNATURE statement that used a /SAVE qualifier. If saved authentication information is present, then the SIGNATURE_BLOCK uses the saved information and does not prompt for any. The SIGNATURE statement similarly will use the saved authentication information in lieu of the authentication information specified on the SIGNATURE statement itself. Note that the purpose and /USER1 through /USER5 qualifier values are only overridden with saved information if they are not specified or are specified as null or blank on the SIGNATURE statement itself. Note that the SIGNATURE_BLOCK or SIGNATURE statement which uses the /SAVE qualifier must be compatible with the SIGNATURE_BLOCK or SIGNATURE statement which uses the /RECALL qualifier. Specifically, both blocks/statements must be either single or double signatures. It is not permissible for the first block/statement to be a single electronic signature and the second to be a double electronic signature (and vice versa). If this occurs in a SIGNATURE_BLOCK, the /RECALL qualifier will be ignored. If this occurs in a SIGNATURE statement, an error will be returned.

5-106

Blocks and Block Qualifiers IAF 8.0 DML

/RHEADING

/RHEADING
Syntax
/RHEADING=string_expression

Description
This qualifier allows you to indicate the column heading for an input block, output block, or yes/no block in a TABLE_EDIT form, or for an output block in a REPORT form. IAF right-justifies the heading over the given column, without truncating the heading to the columns length (for example, the heading can extend over several columns.) You can include a comma in the heading expression to force the heading portion before the comma to display on one line, and the heading portion after the comma to display on the next line. A heading can display over no more than two lines. By default, IAF generates a column heading when it executes the given form. You can center, left-justify, or right-justify each column heading over its related column via the /HEADING, /CHEADING, /LHEADING or /RHEADING block qualifier. For details regarding the /HEADING, /CHEADING and /LHEADING block qualifiers, refer to their descriptions in this section.

Example
/RHEADING=Customer Name

Blocks and Block Qualifiers IAF 8.0 DML

5-107

/ROW

/ROW
Syntax
/ROW=numeric_expression

Description
This qualifiers characteristics depend upon the block statement that specifies it. In general, the /ROW qualifier allows you to indicate the form window row on which input or output is to occur. This qualifier is mandatory for input, item, menu, and yes/no blocks, and is recommended for use with pause blocks. The /ROW qualifier is also mandatory for output blocks that do not reside in REPORT forms. Specifically, the /ROW qualifiers behavior is as follows: For input blocks, this qualifier specifies the form window row on which the input is to occur. For multiple- -line input editing windows (for example; fields with a native datatype of DOCUMENTARY), this qualifier specifies the row on which the first line of the editing window is to be located. For output blocks, this qualifier specifies the form window row on which the output data is to display. For output display areas consisting of multiple lines (as a result of using the /HEIGHT=0 or /HEIGHT=n qualifier), this qualifier specifies the row on which the first line of output is to display. For pause blocks, this qualifier specifies the form window row on which the pause block is to be located. For yes/no blocks, this qualifier specifies the form window row on which the yes/no response input is to occur. For menu blocks, this qualifier specifies the form window row on which the top line of the resulting menu is to display. For item blocks, this qualifier specifies the form window row on which the item blocks tag and optional description are to display.

Example
/ROW=(#HEIGHT/2)

5-108

Blocks and Block Qualifiers IAF 8.0 DML

/SAVE

/SAVE
The /SAVE qualifier is used to save the validated authentication information entered by the user in a SIGNATURE_BLOCK or as specified by the program on a SIGNATURE statement for use by a future SIGNATURE_BLOCK or SIGNATURE statement. Only validated authentication information is saved. The purpose, usernames(s), password(s), and /USER1 through /USER5 qualifier values are saved. The DML compiler issues a compile-time error message when both /SAVE and /RECALL are used at the same time and when /SAVE and /ERASE are used at the same time.

Blocks and Block Qualifiers IAF 8.0 DML

5-109

/SOURCE

/SOURCE
Syntax
/SOURCE=dml_expression

Description
This qualifiers characteristics depend upon the block statement that specifies it. In general, the /SOURCE qualifier specifies the default value of the input for input block types, or the source of the output data for output block types. This qualifier must indicate a valid DML expression. Specifically, the /SOURCE qualifiers behavior is as follows: For an input block, this qualifier allows you to indicate the blocks default input value. If the input block does not indicate a source, IAF uses the input value that the blocks /TARGET qualifier specifies as the default. For an output block, this qualifier allows you to indicate the source of the output data. For an item block, this qualifier allows you to indicate the description that is to display when the block appears on a form. If the item block does not indicate a source, IAF uses the description defined for the given facility via the System Definition Editor. For details regarding facilities and the System Definition Editor, refer to the IAF System Reference Manual. For a menu block, this qualifier allows you to indicate the item tag associated with the menu option that is to be the default selection option. When IAF executes a given menu it prepares the specified tag for immediate selection by automatically placing a reverse video selection bar over it. If the menu block does not indicate a source, or the given expressions value is not a valid tag, the default selection option is the EXIT option, if one exists, or the menus first option, otherwise. For yes/no blocks, this qualifier allows you to indicate the default response to the blocks prompt. A yes/no blocks default response can be either Yes or No. If the yes/no block does not indicate a source, the default response is the value that the /TARGET qualifier specifies, if present, or No, otherwise. The following table indicates the criteria IAF uses to determine the default response to

5-110

Blocks and Block Qualifiers IAF 8.0 DML

/SOURCE

use, based upon the value of the expression that the /SOURCE qualifier specifies. If the expressions value has the following characteristic: Begins with a T or t Begins with a Y or y Is numeric with a non-zero value Is numeric with a zero value Is any other value Yes Yes Yes No No

The default response is:

Examples
INPUT_BLOCK /ROW=5 /COL=3 /SOURCE=#DEFAULT_VALUE & . . INPUT_BLOCK /ROW=5 /COL=3 /SOURCE=PARTS(UNIT_COST) & . . OUTPUT_BLOCK /ROW=10 /COL=20 /SOURCE=#TOTAL_VALUE OUTPUT_BLOCK /ROW=10 /COL=20 &
/SOURCE=(Part & PARTS(PARTS_CODE) & Costs & PARTS(UNIT_COST))

OUTPUT_BLOCK /ROW=10 /COL=20 /SOURCE=PARTS(UNIT_COST) ITEM_BLOCK /ROW=10 /COL=20 /SOURCE=Trial Balance ITEM_BLOCK /ROW=10 /COL=20 & /SOURCE=(#CODE & Option) & . . MENU_BLOCK /ROW=10 /COL=20 & /SOURCE=(#LAST_ITEM_SELECTED) & . . MENU_BLOCK /ROW=10 /COL=20 & /SOURCE=CUSTOMERS(CUST_TYPE) & . . YESNO_BLOCK /ROW=10 /COL=20 & /SOURCE=PARTS(AUTOMATIC_REORDER_FLAG) & . .

Blocks and Block Qualifiers IAF 8.0 DML

5-111

/SOURCE_IF

/SOURCE_IF
Syntax
/SOURCE_IF=(condition_expression),default_expression

Description
This qualifiers characteristics depend upon the block statement that specifies it. In general, the /SOURCE_IF qualifier allows you to indicate conditional sources for blocks. Because a /SOURCE qualifiers implicit condition is always true, IAF ignores any /SOURCE_IF qualifiers or additional /SOURCE qualifiers that follow a /SOURCE qualifier. Therefore, it is advisable to place a blocks /SOURCE_IF qualifier(s) before its /SOURCE qualifier. IAF evaluates each /SOURCE_IF qualifiers condition expression. If a condition expression is true, IAF uses the source that the given /SOURCE_IF qualifier specifies. Otherwise, IAF uses the source that the /SOURCE qualifier specifies. Specifically, the /SOURCE_IF qualifiers behavior is as follows: For an input block, this qualifier allows you to indicate a list of conditional default input data sources. When executing an input block, IAF evaluates each /SOURCE_IF condition expression until one is true, or there are no more to evaluate. IAF uses the source associated with the first /SOURCE_IF qualifier whose condition expression is true (for example; has a non-zero value.) If no /SOURCE_IF qualifiers condition expression is true, IAF uses the source that the /SOURCE qualifier specifies. For an output block, this qualifier allows you to indicate a list of conditional output data sources. When executing an output block, IAF evaluates each /SOURCE_IF condition expression until one is true, or there are no more to evaluate. IAF uses the source associated with the first /SOURCE_IF qualifier whose condition expression is true (for example; has a non-zero value.) If no /SOURCE_IF qualifiers condition expression is to true, IAF uses the source that the /SOURCE qualifier specifies. For a yes/no block, this qualifier allows you to indicate a list of conditional input data sources. When executing a yes/no block, IAF evaluates each /SOURCE_IF condition expression until one is true, or there are no more to evaluate. IAF uses the source associated with the first /SOURCE_IF qualifier whose condition expression is true

5-112

Blocks and Block Qualifiers IAF 8.0 DML

/SOURCE_IF

(for example; a non-zero value.) If no /SOURCE_IF qualifiers condition expression is true, IAF uses the source that the /SOURCE qualifier specifies. For details on how IAF translates data for yes/no blocks, refer to this sections description of the /SOURCE qualifier. For a menu block, this qualifier allows you to indicate a list of conditional default tag sources. When executing a menu block, IAF evaluates each /SOURCE_IF conditional expression until one is true, or there are no more to evaluate. IAF uses the source associated with the first /SOURCE_IF qualifier whose condition expression is true (for example; a non-zero value.) If no /SOURCE_IF qualifiers condition expression is true, IAF uses the source that the /SOURCE qualifier specifies.

Examples
INPUT_BLOCK GET_DISC_PERCENTAGE /ROW=10 /COL=20 & /TARGET=#CUST_DISC & /USING=SALES_ORDERS(DISCOUNT) & /SOURCE_IF=(CUSTOMERS(TYPE)=A),5.00 & /SOURCE_IF=(CUSTOMERS(TYPE)=B),10.00 & /SOURCE_IF=(CUSTOMERS(TYPE)=C),15.00 & /SOURCE=0.00

In this example, if the customer type is A, the default discount is five percent. If the customer type B, the default discount is ten percent. If the customer type is C, the default discount is fifteen percent. If the customer type is not A, B, or C the default discount is zero.
OUTPUT_BLOCK SHOW_CUSTOMER_TYPE /ROW=10 & /COL=20 & /SOURCE_IF=(CUSTOMERS(TYPE)=A),Retail & /SOURCE_IF=(CUSTOMERS(TYPE)=B),Wholesale & /SOURCE_IF=(CUSTOMERS(TYPE)=C),Government & /SOURCE=*Unknown*

In this example, if the customer type is not A, B, or C, the default classification is *Unknown*.
MENU_BLOCK GET_ORDER_ACTION /ROW=2 /COL=4 & /TITLE=Order Action & /ITEM=HOLD, Place order on hold,(PERFORM HOLD_ORDER) & /ITEM=DISPATCH, Dispatch order,(PERFORM DISPATCH) & /ITEM=CONFIRM, Confirm order,(PERFORM CONFIRM) & /ITEM=CANCEL, Cancel order,(PERFORM CONFIRM) & /ITEM=EXIT,,(EXIT) & /SOURCE_IF=(CUSTOMERS(CREDIT_RATING)=A),DISPATCH & /SOURCE_IF=(CUSTOMERS(CREDIT_RATING)=B),CONFIRM & /SOURCE_IF=(CUSTOMERS(CREDIT_RATING)=C),HOLD & /SOURCE=CANCEL

In this example, the Order Action menu displays the DISPATCH, CONFIRM, HOLD, CANCEL, and EXIT options. If the customers

Blocks and Block Qualifiers IAF 8.0 DML

5-113

/SOURCE_IF

credit rating is A, the DISPATCH selection option is the default option. If the customers credit rating is B, the default selection option is CONFIRM. If the customers credit rating is C, the default selection option is HOLD. If the customers credit rating is any other value, the default selection option is CANCEL.
YESNO_BLOCK GET_HOLD_FLAG /ROW=10 /COL=20 & /TARGET=#HOLD_FLAG & /USING=SALES_ORDERS(HOLD_FLAG) & /SOURCE_IF=(CUSTOMERS(CREDIT_RATING)=A),N & /SOURCE_IF=(CUSTOMERS(CREDIT_RATING)=B),N & /SOURCE_IF=(CUSTOMERS(CREDIT_RATING)=C),Y & /SOURCE=Y

In this example, if the customers credit rating is A, the default response is No. If the customers credit rating is C, the default response is Yes. If the customers credit rating is any other value, the default response is Yes.

5-114

Blocks and Block Qualifiers IAF 8.0 DML

/SUCCESS

/SUCCESS
Syntax
/SUCCESS=(success-dml)

Description
This optional qualifier specifies the DML statement that IAF is to execute after the SIGNATURE_BLOCK completes when the usernames(s) and password(s) entered are accepted as valid, both by the operating system and any optional validation routine. For a list of DML statements that the /SUCCESS qualifier can execute, please refer to the appendix on EXECUTING DML STATEMENTS VIA QUALIFIERS in the IAF Data Manipulation Language manual.

Example
/SUCCESS=(CONTINUE COMMIT)

Blocks and Block Qualifiers IAF 8.0 DML

5-115

/TAG

/TAG
Syntax
/TAG=expression

Description
This qualifier allows you to indicate the tag that IAF is to display for the given item to facilitate its selection. The specified tag overrides any tag that has been defined for the given facility via the System Definition Editor. For details regarding facilities and the System Definition Editor, refer to the IAF System Reference Manual. The /TAG qualifiers behavior is identical to the /PROMPT qualifiers behavior when appended to an item block. Therefore, you can append the /TAG qualifier to an item block in place of the /PROMPT qualifier. However, if you append a /TAG qualifier to an item block, and subsequently load the given menu into the forms editor, the forms editor replaces the /TAG qualifier with the /PROMPT qualifier. Upon saving the menu and exiting the forms editor, you can use any text editor to see the change in the code. Although the codes appearance changes, its behavior remains the same. For details regarding the /PROMPT qualifier, refer to its description in this section.

Example
ITEM_BLOCK ORDER_ENTRY /ROW=2 /COL=10 & /FACILITY=ORDER_ENTRY & /TAG=ORD

5-116

Blocks and Block Qualifiers IAF 8.0 DML

/TAG_LENGTH

/TAG_LENGTH
Syntax
/TAG_LENGTH=numeric_expression

Description
This qualifier allows you to indicate a value indicating the given tags length. You can use this qualifier to override the tag length that the given MENU form specifies. By default, IAF places two character positions between the last character of the tag and the beginning of the tag description.

Examples
/TAG_LENGTH=8 /TAG_LENGTH=#SMALL_TAG

Blocks and Block Qualifiers IAF 8.0 DML

5-117

/TARGET

/TARGET
Syntax
/TARGET=data_element

Description
This qualifiers characteristics depend upon the block statement that specifies it. In general, the /TARGET qualifier specifies the storage destination for input data, or the target to which output data is to transfer. The given data element must be a writable (for example; not read-only) table field, variable, or parameter, and cannot be an array element. If the block target is a table field, IAF performs the necessary validation to ensure that the data input or output complies with the given table fields requirements. Specifically, the /TARGET qualifiers behavior is as follows: For an input block, this qualifier allows you to indicate the storage destination for input data. For an output block, this qualifier allows you to indicate the destination to which the given blocks source is to transfer. For a menu block, this qualifier allows you to indicate the storage location of a given tag. For a yes/no block, this qualifier allows you to indicate the storage destination for the input data. A yes/no blocks destination can be only a table field or a variable. If the target for a yes/no block is a table field with a length of one, IAF truncates the input to either Y or N before storing it. Note: If an input blocks /TARGET qualifier specifies a table field, and the domain and target tables are the same, IAF does not write to the table field if the input blocks domain validation succeeds (a record containing the input data exists.) Therefore, any update trigger on the target table field will not be activated under these circumstances. The example on the following page illustrates this.
INPUT_BLOCK DEPT /ROW=1 /COL=20 /TARGET=DEPARTMENTS(DEPT)

5-118

Blocks and Block Qualifiers IAF 8.0 DML

/TARGET

Assuming that DEPT is the sole PID field for the DEPARTMENTS table, and the department number entered for the input already exists in the DEPARTMENTS table, IAF does not update the DEPT field. For multiple-field PIDs, IAF does not perform domain validation until data entry takes place for the last PID field. Therefore, IAF writes to all PID fields except the last one if a record containing the entire PID entry exists. This means that an update trigger on any PID field except the last one would be activated, while an update trigger on the last PID field would not be activated.

Examples
/TARGET=#CUSTOMER_ID /TARGET=SALES_ORDERS(CUSTOMER_ID)

Blocks and Block Qualifiers IAF 8.0 DML

5-119

/TITLE

/TITLE
Syntax
/TITLE=title

Description
This optional qualifier specifies a value to replace the default title displayed on the signature form. Title can be a quoted string literal, variable or expression enclosed within parentheses.

Example
/TITLE="Authorized Signature"

5-120

Blocks and Block Qualifiers IAF 8.0 DML

/TOTAL

/TOTAL
Syntax
/TOTAL

Description
This qualifier causes IAF to automatically accumulate and print a total for the given numeric output block at the end of each level break in a report. Grand totals print at the end of the report. Note that the /TOTAL qualifier is applicable only to numeric output blocks on REPORT forms. Each output block that specifies the /TOTAL qualifier is identifiable via a unique number from 1-100 (for example; 1 for the first output block that specifies the /TOTAL qualifier, 2 for the second, and so on, to a maximum of 100 for a given DML source file.) IAF provides the TOTAL(n) built-in function to facilitate retrieving the current value of a given blocks total, where n is the number associated with the given block. For details regarding TOTAL(n) and other built-in functions, refer to this manuals BUILT-IN FUNCTIONS chapter. If an output block specifies the /BREAK qualifier and the /TOTAL qualifier, and the output blocks value is print suppressed (as a result of the /BREAK=%NOTOTAL form option), IAF suppresses the totaling of the output blocks source value. For details regarding /BREAK=%NOTOTAL, refer to this manuals Forms and Form Qualifiers chapter.

Blocks and Block Qualifiers IAF 8.0 DML

5-121

/TOTAL

Example
REPORT_FORM MAIN & /READ_ONLY & /WIDTH=80 & /OUTPUT=(MOVIES_REPORT) & /TABLE=MOVIES & /SORTED_BY=(MOVIES(MOVIE_TYPE)) & /BREAK=%LINES_AFTER=1,(MOVIES(MOVIE_TYPE)) & /LHEADING=(%NOW) & /RHEADING=(MASK(Page !-@@@@@, %PAGE)) & /HEADING=(Movie Report) OUTPUT_BLOCK MOVIE_ID /SOURCE=(MOVIES(MOVIE_ID)) OUTPUT_BLOCK TIMES_RENTED /SOURCE=(MOVIES(TIMES_RENTED)) & /TOTAL
OUTPUT_BLOCK REVENUE /SOURCE=(MOVIES(PRICE)*MOVIES(TIMES_RENTED)) &

/USING=MOVIES(PRICE) & /TOTAL & /HEADING=TOTAL,REVENUE END_FORM

5-122

Blocks and Block Qualifiers IAF 8.0 DML

/USE_IF

/USE_IF
Syntax
/USE_IF=(condition_expression)

Description
This qualifier allows you to conditionally execute the block that specifies it, and is applicable to every block type except DML blocks. If the expression that this qualifier specifies is false (for example; its value is zero), IAF does not execute the block. If the expression is true (its value is not zero), IAF executes the block. Using this qualifier is equivalent to enclosing the block in an IF/END_IF construct. The advantage of using this qualifier is that IAF evaluates the condition expression before initially displaying the form. Therefore, any prompt associated with the block does not display if the expression is false. However, because IAF evaluates the expression before displaying the form, the expression should not include a variable whose value is obtained by the form. Any DML code that is attached to the block executes even if the given condition expression is false. For details regarding attached DML code, refer to this chapters Introduction section.

Examples
INPUT_BLOCK CURRENCY_CODE /ROW=10 /COL=40 & /TARGET=CUSTOMER(CURRENCY_CODE) & /PROMPT=FIELD_PROMPT(CURRENCY_CODE) & /USE_IF=(#MULTI_CURRENCY=Y) ITEM_BLOCK CURRENCY_CODE /ROW=10 /COL=40 & /FACILITY=MAINTAIN_CURRENCIES & /USE_IF=(#MULTI_CURRENCY=Y)

Blocks and Block Qualifiers IAF 8.0 DML

5-123

/USERNAME1

/USERNAME1
Syntax
/USERNAME1=username-1

Description
This optional qualifier specifies the location in which to return the first username entered by the end-user. Username-1 can be any variable or table field that is acceptable as the target of an input block. . You may omit this qualifier if you do not need to receive the first username as a target variable in your DML program. The first username entered by the user is still authenticated by the operating system and any validation form, even when this qualifier is omitted.

Example
/USERNAME1=E_SIGNATURES(PRIMARY_SIG)

5-124

Blocks and Block Qualifiers IAF 8.0 DML

/USERNAME2

/USERNAME2
Syntax
/USERNAME2=username-2

Description
This optional qualifier specifies both that a double electronic signature is to be performed and the location in which to return the second username entered by the end-user. Username-2 can be any variable or table field that is acceptable as the target of an input block. If you do not need to receive the second username as a target variable in your DML program, then use the /DOUBLE qualifier instead of the /USERNAME2 qualifier. When a double signature is specified, the values in the first and second username entries must not be the same. The second username entered by the user is authenticated by the operating system and any validation form, even when this qualifier is omitted.

Example
/USERNAME2=E_SIGNATURES(SECONDARY_SIG)

Blocks and Block Qualifiers IAF 8.0 DML

5-125

/USER1-5

/USER1-5
Syntax
/USER1=user-defined-1 /USER2=user-defined-2 /USER3=user-defined-3 /USER4=user-defined-4 /USER5=user-defined-5

Description
These optional qualifiers specify values that are passed to the validation form and also recorded in the signature audit file. Their use and purpose is under the control of the validation form. User-defined-1 through userdefined-5 may be quoted string literals, functions, table fields, variables, special variables, or expressions enclosed in parentheses.

Example
/USER1=MANAGER

5-126

Blocks and Block Qualifiers IAF 8.0 DML

/USER_KEYn

/USER_KEYn
Syntax
/USER_KEYn=(dml_statement)

Description
This qualifier allows you to indicate the action IAF is to take when the end user presses a user- definable function key on an input block, and may be specified for more than one key per block. User- definable function keys are GM_USER1 through GM_USER20. You do not have to assign function key actions in sequential order.

Examples
/USER_KEY1=(GOTO INPUT_1)

This qualifier indicates that if the end user presses the GM_USER1 key at the input block that specifies this qualifier, IAF is to execute the given GOTO statement.
/USER_KEY6=(PERFORM MEMBERS_RENTALS)

This qualifier indicates that if the end user presses the GM_USER6 key at the input block that specifies this qualifier, IAF is to execute the given PERFORM statement.

Blocks and Block Qualifiers IAF 8.0 DML

5-127

/USING

/USING
Syntax
/USING=keyword[,keyword[,...]]

or
/USING=table_name(field_name)[,keyword[,...]]

Description
This qualifiers characteristics depend upon the block statement (for example; INPUT_BLOCK or OUTPUT_BLOCK) that specifies it. In general, the /USING qualifier allows you to indicate attributes to apply to the given blocks data.

For input blocks:

This qualifier allows you to validate input block data and can use either of the syntax formats given under the Syntax heading on the preceding page. Therefore, a /USING qualifier on an input block must include at least a keyword or a table field specification, but may include multiple keywords. The /USING qualifier may indicate keywords in any logical combination, to indicate attributes and/or rules to apply to the input data. The following table lists and describes the effects of the keywords that are valid for use with the /USING qualifier on an input block. Keyword ALPHA DATE FULL Effect The input data must be alphabetic. The input data must be a valid date. The input data must completely fill the target field. This does not apply to a null entry (for example; zero followed by GM_CR), which the input will still allow. To disallow null entries, use the REQUIRED keyword. The input accepts characters until the target field is full. Control then transfers to the next input.

KEYPUNCH

5-128

Blocks and Block Qualifiers IAF 8.0 DML

/USING

Keyword MULTIPLE

Effect The input data can consist of multiple values and/or ranges delimited by commas, and takes place via a table edit window. All input data, except ranges, can include wildcard characters. Valid wildcard characters are * and %, where * represents zero or more unknown characters, and % represents a single unknown character. By default, IAF performs domain validation for any implicit and/or explicit domains that exist for the table field that the /USING qualifier specifies. However, IAF does not validate values that include wildcard characters. This keyword is applicable only to input blocks that have a /USING qualifier that specifies a table field that does not have a DOCUMENTARY native datatype, and a target that is a variable or parameter. This keyword facilitates producing a list of values and ranges for use in record selection with the AMONG selection operator.

NOECHO NOLOWER NONEGATIVE NOZERO NUMERIC PASSWORD REQUIRED SCALE=integer

The input data does not echo to the screen. This is useful for password entries. All input characters convert to uppercase. The input value cannot be a negative number. The input value cannot be zero. The input data must be numeric. The input value will be echoed as asterisks (*). This is useful for password entries. The input cannot be left blank. The input value cannot have more than the number of decimal places that the given integer indicates.

If the /USING qualifiers specification includes a table field name, IAF ensures that the input data meets the table fields requirements. IAF uses the validation requirements of any keywords that the /USING qualifier specifies in addition to those of the specified table field.

Blocks and Block Qualifiers IAF 8.0 DML

5-129

/USING

For output blocks:

This qualifier allows you to indicate the name of the table field whose attributes (for example; output mask, heading, etc.) IAF is to apply to the output data. There are no keywords available for use with the /USING qualifier on an output block. Therefore, an output blocks /USING qualifier specifies only a table field name.

Examples
OUTPUT_BLOCK QTY /ROW=11 /COL=30 & /SOURCE=#QTY /USING=PARTS(QUANTITY)
OUTPUT_BLOCK REVENUE /SOURCE=(MOVIES(PRICE)*MOVIES(TIMES_RENTED)) &

/USING=MOVIES(PRICE) /TOTAL /HEADING=TOTAL,REVENUE INPUT_BLOCK LAST_NAME /ROW=15 /COL=25 & /TARGET=EMPLOYEES(LAST_NAME) /USING=NOLOWER,REQUIRED INPUT_BLOCK CUST_ID /ROW=14 /COL=40 & /TARGET=#CUST_ID & /USING=SALES_ORDERS(CUSTOMER_ID),NUMERIC INPUT_BLOCK DEPT /ROW=18 /COL=50 & /TARGET=#DEPT /USING=SALES_ORDERS(DEPARTMENT),MULTIPLE

Given this input block, an end user could enter the following department data:
101,104,213-218,31%,4*,515,644-650

indicating that the requested departments are 101, 104, 213-218, 310-319, 400-499, 515, and 644-650. The end user would enter this data in a table edit window having the following format: From 101, 104, 213 31%, 4*, 515, 644 650 218 To

5-130

Blocks and Block Qualifiers IAF 8.0 DML

/VALIDATION

/VALIDATION
Syntax
/VALIDATION_FORM=form-name

Description
This optional qualifier specifies the name of a validation form that IAF executes after all signature inputs have been completed by the end-user and before the username(s) and password(s) are authenticated by the operating system. (A PROCEDURE_FORM is recommended for this purpose.) The validation form must be located within the same form file as the SIGNATURE_BLOCK. See below for more information on the use of validation forms.

Example
/VALIDATION_FORM=cross_check_users

Blocks and Block Qualifiers IAF 8.0 DML

5-131

Chapter 6

Language Statements

This chapter lists and describes the various language statements that IAFs DML includes. A language statement can consist of multiple elements (e.g. qualifiers, keywords, file specifications, database handles, routine names, arguments, expressions). Language statements enable you to manipulate items such as records and record buffers, screen input and output, and program logic in general. All language statements are executable at the IAF command line prompt (GEM> by default) as well as within DML programs. However, statements that have interdependencies, loops, or one or more /STATISTIC qualifiers will not produce meaningful results when executed at the IAF command line prompt. This chapter consists of the Language Statements table followed by a description of each language statement, presented in alphabetical order by statement. The Language Statements table groups language statements into the following major categories: Program Flow Data Access Text File Management Screen Input and Output System Settings Inter-Process Communication client/server Environment Utilities and Program Development Additionally, the table groups various functionally disparate language statements under the Miscellaneous category. The Language Statements table makes it easy to quickly look up a given language statement and its syntax, and to obtain a brief overview of the statements function. Following the Language Statements table is an in-depth discussion of each language statement, including the given statements syntax, a full description of the statements function, an example program extract illustrating the statements use, and a list of any related topics.

6-2

Language Statements IAF 8.0 DML

Language Statements Table

Language Statements Table

The following table lists and describes DML statements by function. Following this table are detailed descriptions of these statements, in alphabetical order by statement name. Category Program Flow Language Statement BEGIN_CASE (initial_expression) CASE expression[,expression[,...]] or CASE operator expression or CASE expression_a TO expression_b or CASE ELSE END_CASE BEGIN_DISABLE_TRIGGER BEGIN_SIGNAL_TO_STATUS CALL routine_name [(argument1[,argument2[,...]])] CALL_WEB_SERVICE & [/ACTION=action] & [/OPERATION=operation] & [/PARAMETER=(NAME=name, TYPE=type, VALUE=value)] & [/NAMESPACE=namespace] & [/URL=url] & [/RESPONSE=response] & [/RESULT=(NAME=name, TYPE=type, TARGET=target)] CLEAR_ARRAY #array() This statement causes the specified array to be cleared. The cleared array has zero elements. Go to the next loop iteration. Provide DML code to execute if an IF condition fails. Disable update triggers. Begin trapping signaled errors. Call an external routine. Permits DML programs to call Web Services. Function Indicate a constant value against which to evaluate a given expression.

CONTINUE [keyword] ELSE (see IF)

Language Statements IAF 8.0 DML

6-3

Language Statements Table

Category ELSE_IF (see IF) END_GTID

Language Statement

Function Provide a condition to evaluate if a preceding IF/ELSE_IF condition fails. This statement decrements the %GTID_LEVEL (Global Transaction Identifier Level) special variable. Re-enable update triggers. End a compound IF statement. Stop trapping signaled errors. End a compound WHILE statement. Exit the current form. Branch to a given block.

END_DISABLE_TRIGGER (see BEGIN_DISABLE_TRIGGER) END_IF (see IF) END_SIGNAL_TO_STATUS END_WHILE (see WHILE) EXIT [(exit_status)] GOTO block_name

6-4

Language Statements IAF 8.0 DML

Language Statements Table

Category Program Flow

Language Statement IF (condition_expression) dml_statement or IF (condition_expression) dml_code ELSE dml_code END_IF or IF (condition_expression) dml_code ELSE_IF (condition_expression) dml_code [ ELSE_IF (condition_expression) dml_code ] END_IF or IF (condition_expression) dml_code ELSE_IF (condition_expression) dml_code [ ELSE_IF (condition_expression) dml_code ] ELSE dml_code END_IF PERFORM [/NODEADLOCK_EXIT] & form_name [(argument1[,argument2[,...]])] or PERFORM [/BATCH[=PRINT]] & form_file_spec [(argument1[,argument2[,...]])] or PERFORM [/BATCH[=PRINT]][/NODEADLOCK_EXIT] & form_file_spec form_name [(argument1[,argument2[,...]])] or PERFORM /FACILITY DB.SYS:FAC [(argument1[,argument2[,...]])] or PERFORM /ARRAY[=count] #array()[form_name] [(argument1[,argument2[,...]])]

Function Conditionally execute DML code.

Execute a form.

Language Statements IAF 8.0 DML

6-5

Language Statements Table

Category

Language Statement SWITCH form_name [(argument1[,argument2[,...]])] or SWITCH form_file_spec & [form_name] [(argument1[,argument2[,...]])] or SWITCH /FACILITY [[database-handle.][system-name:]]facility-name SWITCH_BASE [%EXIT] or SWITCH_BASE form_name [(argument1[,argument2[,...]])] or SWITCH_BASE form_file_spec & [form_name] [(argument1[,argument2[,...]])]

Function Switch control to a different form.

Switch control to the /BASE form.

Program Flow

WHILE (condition_expression) dml_statement or WHILE (condition_expression dml_code END_WHILE

Create a conditional loop.

Data Access

ADD TO [database_handle.]table_name [/NOERROR] or ADD TO #variable_name [/NOERROR]

Add records to a given table.

Metadata Metadata

ADD MANAGER_ROLE [user_name:role_name] ADD ROLE_MANAGER [role_name:user_name] ARCHIVE [DBMS] [{FROM|SOURCE}] from_database_handle [{TO|TARGET}] to_database_handle &

Adds an entry to table GEM_ROLE_USERS. Adds an entry to table GEM_ROLE_USERS. All marked rows in all archivable tables within the source database are copied to the same named tables in the target database, then deleted from the source. Check a given domain.

CHECK_DOMAIN [label_name] & /TARGET=table_name(field_name) [/qualifiers] or CHECK_DOMAIN [label_name] & /USING=table_name(field_name) [/qualifiers]

6-6

Language Statements IAF 8.0 DML

Language Statements Table

Category

Language Statement CLEAR_BUFFER [database_handle.]table_name or CLEAR_BUFFER #variable_name CLOSE datafile_handle COMMIT DELETE [/ARCHIVE] [ALL] FROM & [database_handle.]table_name or DELETE [/ARCHIVE] [ALL] FROM #variable_name

Function Clear the given tables user buffer.

Close an unrelated RMS table file. Commit the current transaction. Delete the record currently in the buffer from the given table, or delete all records from the table. Deletes entry(ies) from table GEM_ROLE_USERS with an M in the GEM_USER_TYPE column. Deletes entry(ies) from table GEM_ROLE_USERS with an M in the GEM_USER_TYPE column. Fetch the streams next record. Find a record in the given table. Close a database. Open a database. Load a text file into a segmented string field. Open an unrelated RMS table file. Roll back the current transaction.

Data Access

DELETE MANAGER_ROLE [user_name:role_name1, role_name2, etc...]

Data Access

DELETE ROLE_MANAGER [role_name:user_name1, user_name2, etc...]

FETCH stream_name [/qualifiers] FIND IN [stream_name:|database_handle.]table_name & [/qualifiers] FINISH database_handle INVOKE database_spec AS database_handle [/qualifiers] LOAD file_spec INTO & [database_handle.]table_name(field_name) OPEN unrelated_table_file AS datafile_handle [/qualifiers] ROLLBACK

Language Statements IAF 8.0 DML

6-7

Language Statements Table

Category Data Access

Language Statement SET CAT_FILTER

Function Sets a string_expression (table name) to a special variable %CAT_FILTER. Start a record stream.

START_STREAM stream_name & /TABLE=[database_handle.]table_name[,table_name[,... ]] & [/qualifiers] or START_STREAM stream_name & /TABLE=#variable_name[,#variable_name[,...]][/qualifie rs] START_TRANSACTION [READ_ONLY] UNLOAD file_spec FROM & [database_handle.]table_name(field_name) MSSQL Server Engine: VERIFY [user-name/password/databasename@DNSName] /ENGINE=MSSQL /MAX_ERRORS=[Number of errors] /OUTPUT=GEM_RUN:[File_name] ORACLE Server Engine: VERIFY [username/password/schema@Connection_String] /ENGINE=ORACLE /MAX_ERRORS=[Number of errors] /OUTPUT=GEM_RUN:[File_name] Text File Management CLOSE_TABS [/optional qualifiers]

Start a transaction. Unload a segmented string field into a file. Opens a database, verifies IAF metadata consistency as well as applications data contained and lists any errors found either on the screen or saved to a file. This command is fully documented under the Database Integrity Checker description. It has been developed like an involk command.

Closes the currently-opened tabs.

6-8

Language Statements IAF 8.0 DML

Language Statements Table

Category

Language Statement OPEN_TAB [/URL=[StringExpression] /WEB_APP=[String Expression] /FACILITY=[String Expression] /PERFORM=[String Expression]] [/DESC=[String Expression]/NEW_WINDOW] CLOSE_TEXT tag OPEN_TEXT [/APPEND|/CREATE] filename AS tag READ_LINE tag [/TARGET=target_spec] REWIND_TEXT tag

Function Allows opening either a TAB within an iBrowser session or another browser session with either a URL or a WEB_APP specification. Close the given text file. Open the specified file. Read a record from the given text file. Position the current record at the beginning of the specified file. Write data into the record buffer associated with the given file. Write a record to the given text file. Redisplay the current form. Erase all or part of a form window. Display or clear error text.

WRITE tag data

WRITE_LINE tag [data] Screen Input and Output DISPLAY keyword ERASE [/qualifiers] ERROR [/qualifiers] error_text or ERROR ERROR_TEXT(error_no, flags [,argument1[,argument2[,...]]]) LINE /ROW=numeric_expression & /COL=numeric_expression & [/END_ROW=numeric_expression] & [/END_COL=numeric_expression] MENU [database_handle.][system_name:]facility_name

Print lines or boxes on a form. For details, refer to this manuals Fixed Display Declarations chapter. Execute a menu defined via the System Definition Editor.

Language Statements IAF 8.0 DML

6-9

Language Statements Table

Category Screen Input and Output

Language Statement MESSAGE[/qualifiers] [database_handle.] & message_name[,argument1[,argument2[,...]]] or MESSAGE PRINT [/qualifiers] expression TABLE_SEARCH [database_handle.] & table_name(field_name1[,field_name2[,...]]) [/qualifiers] TEXT /ROW=numeric_expression & /COL=numeric_expression [{token}]text

Function Display or clear a message.

Display the evaluated expression. Allows the end user to search through a table of records. Print text on a form. For details, refer to this manuals Fixed Display Declaratios chapter. Specify access mode for a database table or an unrelated table file.

System Settings

SET ACCESS table_name [access_mode] & [/SHARE=share_mode] or SET ACCESS table_name & /RMS_OPTIONS=rms_option[,rms_option[,...]] SET [/LOCAL] DATABASE database_handle SET DATE_FORMAT format_name SET ENTRY_MENU & [database_handle.][system_name:]facility_name or SET ENTRY_MENU SET HELP ON SET HELP OFF SET ICON_NAME string_expression

Specify the default database. Specify optional date input format. Specify the menu to execute upon invoking IAF, or disable automatic menu execution. Allows single line help text at the bottom of the screen. Disable single line help text at the bottom of the screen. Specify text that is to appear below the IAF icon in environments that support a graphical user interface. Specify display attributes for screen output areas.

SET INPUT BACKGROUND attribute[,attribute[,...]]

6-10

Language Statements IAF 8.0 DML

Language Statements Table

Category

Language Statement SET INPUT FOREGROUND attribute[,attribute[,...]]

Function Specify display attributes for screen input areas. Specify the DML statement to execute when an end user presses the GM_INTERRUPT key. Assign a physical key to a logical key name. Specify the file that contains the keyboard definitions to use. Specify the locking strategy IAF is to use. Specify the number of seconds to wait at an input block without input before exiting if there is a readwrite transaction on the database. Specify the type of file to perform when executing a PERFORM, SWITCH, or SWITCH_BASE statement that does not specify a filetype. Specify the numeric precision to use. Specify the IAF command line prompt to use. Specify the screen characteristic(s). Specify the number of forms that are to remain on screen before removing old images. This statement adjusts the rate in seconds at which status displays are updated.

System Settings

SET INTERRUPT dml_statement_expression

SET KEY physical_key_name [/qualifiers] logical_key_name SET KEYBOARD filename

SET LOCK option_keyword[,option_keyword[,...]] SET LOCK_TIMEOUT seconds

SET PERFORM option_keyword

SET PRECISION floating_point_number SET PROMPT expression SET SCREEN option_keyword[,option_keyword] SET SHADOWS number

SET STATUS_FREQUENCY seconds

Language Statements IAF 8.0 DML

6-11

Language Statements Table

Category

Language Statement SET SYSTEM [database_handle.]system_name SET TIMEOUT seconds

Function Specify the default system. Specify the number of seconds to wait at an input block without input before exiting. Specify the DML file to execute when a TITLE statement executes or a IAF utility is invoked. Specify text that is to appear in the title bar of the IAF application window in environments that support a graphical user interface. Enable/disable command display when IAF executes an indirect command file. Show the name of the current default database. Show the current date input format. Show the entry menus name. Show the current single line help text mode. This statement shows the text that appears below the Thin Client and GCWPRO icons. This statement shows the foreground and background display attributes to use for screen output areas (these include input areas after input is done). Show the statement to execute when an end user presses the GM_INTERRUPT key.

SET TITLE_FORM filename

System Settings

SET TITLE_BAR string_expression

SET VERIFY SET NOVERIFY SHOW DATABASE SHOW DATE_FORMAT SHOW ENTRY_MENU SHOW HELP SHOW ICON NAME

SHOW INPUT

SHOW INTERRUPT

6-12

Language Statements IAF 8.0 DML

Language Statements Table

Category

Language Statement SHOW KEYBOARD SHOW LOCK SHOW LOCK TIMEOUT

Function Show the name of the keyboard definition file. Show the current lock mode(s). This statement displays the number of seconds that IAF is to wait for a response at an input block of any kind before timing out, and is applicable only when an end user has a current readwrite transaction on the database. Show the type of file IAF is to perform when executing a PERFORM, SWITCH, or SWITCH_BASE statement that does not specify a filetype. Show the numeric precision in use. This statement shows the currently set DML developer's command line interface prompt. By default, the DML developer's command line prompt is "DML> ". Show the number of forms that must be on the screen before removing old images. This statement displays the frequency at which status displays are updated. Show the name of the current default system. Show the number of seconds to wait at an input block without input before timing out.

SHOW PERFORM

SHOW PRECISION SHOW PROMPT

SHOW SHADOWS

SHOW STATUS FREQUENCY

SHOW SYSTEM SHOW TIMEOUT

Language Statements IAF 8.0 DML

6-13

Language Statements Table

Category

Language Statement SHOW TITLE_BAR

Function This statement shows the text that appears in the Thin Client and GCWPRO title bars. Show the name of the DML file to execute when a TITLE statement executes or a IAF utility is invoked. This statement displays the ON/OFF indirect command file execution verification setting as set with the SET VERIFY or SET NOVERIFY statements. The SIGNATURE statement provides the application developer with the means to perform a noninteractive electronic signature.

SHOW TITLE_FORM

SHOW VERIFY

SIGNATURE [/AUDIT=audit-file-specification] [/DATETIME=date-time] [/FACILITY=[[database-handle.][systemname:]]facility-name] [/FAILURE=(failure-dml)] [/NOAUDIT] /PASSWORD1=password-1 [/PASSWORD2=password-2] [/PURPOSE=purpose] [/SUCCESS=(success-dml)] /USERNAME1=username-1 [/USERNAME2=username-2] [/USER1=user-defined-1] [/USER2=user-defined-2] [/USER3=user-defined-3] [/USER4=user-defined-4] [/USER5=user-defined-5] [/VALIDATION_FORM=form-name] [/additional-qualifiers]

6-14

Language Statements IAF 8.0 DML

Language Statements Table

Category START_GTID

Language Statement

Function This statement increments the %GTID_LEVEL (Global Transaction Identifier Level) special variable. The XML_RECEIVE_TABLES statement receives a stream of XML tables from the Connect client. This statement packages a table as an XML stream and sends the XML to the Connect client. Send an e-mail message.

XML_RECEIVE_TABLES

XML_SEND_TABLE

Inter-Process
Communication

MAIL /TO=to_address [/SUBJECT=subject_text] & /FILE=send_file_spec or MAIL /TO=to_address [/SUBJECT=subject_text] & /TEXT=text_line [/TEXT=text_line[...]] RECEIVE resource_name [/qualifiers] RELEASE resource_name

Receive an inter-process message. Release the given resource from inter-process communication. Send an inter-process message. Establish a Client/Server link.

SEND resource_name [/qualifiers] message_text Client/Server Environment CONNECT [/qualifiers] application_name or CONNECT [/qualifiers] application_name AS connect_handle DISCONNECT [/SESSION] connect_handle END_EXECUTE [/CONNECT=connect_handle] & [writable_data_element[,...]] EXECUTE [/CONNECT=connect_handle] procedure_name & [(argument1[,argument2[,...]])]

Terminate the client/server link. Abort the currently executing procedure. Execute the given procedure.

Language Statements IAF 8.0 DML

6-15

Language Statements Table

Category

Language Statement RECEIVE_DATA [/CONNECT=connect_handle] & writable_data_element[,...] RECEIVE_TABLE [/qualifiers] target_table_name & [FROM [database_handle.]source_table_name] SEND_DATA data_element[,data_element[,...]] SEND_TABLE [/qualifiers] source_table_name & [TO [database_handle.]target_table_name] SEND_MESSAGE numeric_expression, text_expression

Function Get row data from the currently executing procedure. Receive a table from a database to which the Server is attached. Send row data to the Client. Send a table to a database to which the Server is attached. Send an out of band message to a Client. Used to call a method of the COM/Active X object and to get or set properties.

Utilities and Program Development

COCALL [return_value=] COCALL object_handle.method [(argument1, argument2, )] or [return_value=] COCALL #variable_obj.method [(argument1, argument2, )] or COCALL object_handle.method [(argument1, argument2, )]=assign_expression or COCALL #variable_obj.method [(argument1, argument2, )]=assign_expression COCREATE co_name AS object_handle [/LOCATION=server_location] & [/PREF=server_type1[,server_type2[,server_type3]]] [/CLIENT] or COCREATE #variable_name AS #variable_obj [/LOCATION=#variable_loc] & [/PREF=server_type1[,server_type2[,server_type3]]] [/CLIENT] COMPILE [/qualifiers] input_file_spec [output_file_spec]

Used to create an instance of the COM/Active X object.

Compile a DML file.

6-16

Language Statements IAF 8.0 DML

Language Statements Table

Category

Language Statement CORELEASE obj_handle or CORELEASE #variable_obj CROSS_REFERENCE DOCUMENTATION EDIT/DICTIONARY EDIT/FORMS [file_spec] EDIT/REPORTS [file_spec] EDIT/SECURITY EDIT/SYSTEM EDIT/TABLE [/FIND] [database_handle.] & [table_name[(field_name1[,field_name2[,...]])]] FILES [/qualifiers] [file_spec] GENERATE/FORMS GENERATE/REPORTS QUERY [/READ_ONLY] [database_handle.] & table_name[(field_name1[field_name2[,...]])]] REPORT SHOW FIELDS FOR table_specification or SHOW TABLES FOR field_specification TRIGGER trigger_name UTILITIES

Function Unloads and removes any references to a particular COM object. Invoke IAFs CrossReferences utility. Invoke the System Documentation menu. Invoke the Data Definition Editor. Invoke the Forms Editor. Invoke the Report Editor. Invoke the Security Editor. Invoke the System Definition Editor. Invoke the Table Editor. Invoke the File Manager. Invoke the Forms Generator. Invoke the Report Generator. Invoke the Query Interface. Invoke IAFs Reporting Environment. Display the fields in the given table(s), or the tables that hold the given field(s). Perform trigger DML code. Invoke IAFs main Utilities menu.

Language Statements IAF 8.0 DML

6-17

Language Statements Table

Category Miscellaneous CD directory

Language Statement

Function Sets the users current working directory (default directory). See also SET DEFAULT and SET WD. Issue an operating system command. Issue an operating system command. Display simple file directories. Edit the given file via the default text editor. Declare an external routine.

CLI [/qualifiers] command_expression DCL [/qualifiers] command_expression DIR file_specification Miscellaneous EDIT filename EXTERNAL file_spec routine_name & [function_return_value] [(argument1[,argument2[,...]])] License

For administrative users, brings up the Ross Systems Automated Licensing main menu. Shows the current working directory (default directory). See also SHOW DEFAULT and SHOW WD statements and %WD special variable. Seeds the random number generator. See the RANDOM function. Reset the line count in a report.

PWD

RANDOMIZE

REPOSITION BY [-]nnn or REPOSITION TO nnn SEARCH string SET BROADCAST broadcast_categories

Search for metadata entities. Enables or disables broadcast message categories for thin client and character cell users on OpenVMS.

6-18

Language Statements IAF 8.0 DML

Language Statements Table

Category

Language Statement SET DEFAULT directory

Function Sets the users default directory (current working directory). See also CD and SET WD statements. This statement shows the table associated with the GEM_CAT_RELATION_F IELDS_FILTER virtual table and the special variable %CAT_FILTER Sets the users current directory (default directory). See also the CD and SET DEFAULT statements. Shows the users default directory (current working directory) See also the PWD and SHOW WD statements and the %WD special variable. Shows a space-separated list of HOSTIDs for the machine on which IAF is running. See also the %HOSTID special variable. Shows the operating system platform that is used by IAF licensing. See also the %PLATFORM special variable. Shows the TARGETID for the machine on which IAF is running. See also the %TARGETID special variable. This is used by IAF licensing. This is an obsolete statement.

SHOW CAT_FILTER

SET WD directory

SHOW DEFAULT

SHOW HOST ID

SHOW PLATFORM

SHOW TARGETID

Language Statements IAF 8.0 DML

6-19

Language Statements Table

Category SHOW WD

Language Statement

Function Shows the users current working directory (default directory). See also the PWD and SHOW DEFAULT statements and the %WD special variable. Transfer flat files to the current database via a command file. Perform an operating system command.

TRANSFER command_filename

$ operating_system_command

The following pages describe these DML statements and their qualifiers in detail. Unless specified otherwise, each qualifier is applicable only once to a given DML statement.

6-20

Language Statements IAF 8.0 DML

ADD ADMIN_ID

ADD ADMIN_ID
Syntax
ADD ADMIN_ID "role_name:admin_id"

Category
Program flow

Description
This command adds the requested admin into the current database for the specified role. role_name This is a string that represents a valid role name for which the requested admin will be added into the current database. admin_id This is the admin ID to be added into the database for the specified role. An admin_id is a valid user_id. The max number of admin ids/role to be added into the database is twenty, but only one at a time can be added. The case treatment (mixed case) of the admin id is the same as the existing GEMBASE facility security user id.

Example
ADD ADMIN_ID "ADMIN:bob"

! Adds Bob to the ADMIN role. !

Language Statements IAF 8.0 DML

6-21

ADD ROLE

ADD ROLE
Syntax
ADD ROLE role-name [/DESCRIPTION=description] [/ADD_FACILITIES=add-facilities]

Category
Program flow

Description
This DML statement adds the specified role to the current database. If the /ADD_FACILITIES qualifier is used, the specified facilities are associated with the role. role-name A literal, quoted literal or variable containing the name of the role to be added to the database. A role name is a character string with a max length of thirty-one characters and is case insensitive. description A literal, quoted literal or variable containing the new description of the role. add-facilities A literal, quoted literal or variable containing a comma-separated list of system:facility pairs. The specified set of system:facility pairs will be associated with the role. The addition of the role to the facilities is not automatic with the addition of the role. They are separate transactions. The facilities specified in addfacilities are checked at run-time before the role is added to ensure that They are syntactically valid They exist in the database The user has modify-access to them.

6-22

Language Statements IAF 8.0 DML

ADD ROLE

If any of these checks fail, then the role is not added. Not withstanding the up-front checks, if for any reason the addition of the role to the specified facilities should still fail, the additions will stop with the first failure and no further additions will take place. For metadata auditing purposes, this statement is audited as an ADD ROLE role-name statement followed by successive MODIFY FACILITY add-facility /ADD_ROLE=role-name statements.

Examples
ADD ROLE "ADMIN"

Adds an ADMIN role to the database without any description.

ADD ROLE "SALES" /description="this is the salespersons role

Adds the SALES role, with its description, to the database.

ADD ROLE "SALES" /DESCRIPTION="This is the salespersons role /ADD_FACILITIES= "Sys1:Fac1,Sys2:Fac2,,SysN:FacN"

Adds SALES role with its description to the database. Adds the list of facilities to the role SALES.

Language Statements IAF 8.0 DML

6-23

ADD ROLE_USER

ADD ROLE_USER
Syntax
ADD ROLE_USER "role_name:user_id"

Category
Program flow

Description
This command adds the requested user to the specified role in the current database. role_name This is the role for which the specified user name will be added. user_id This is a string that represents the users to be added to the specified role into the current database. The maximum number of users to be assigned to a role is fifty; but it can be assigned one at a time. GSRI will generate an error message if a role exceeds maximum number of users assigned to it.

Example
ADD ROLE_USER "DEV:dinats"

Adds user dinats to role DEV.

6-24

Language Statements IAF 8.0 DML

ADD TO

ADD TO
Syntax
ADD TO [database_handle.]table_name [/NOERROR]

or
ADD TO #variable_name [/NOERROR]

Category
Data access

Description
This statement adds a record to the specified table. The new records data comes from the user buffer associated with the tables primary stream. If this statements execution takes place within a form, and the record addition succeeds, the %STATUS special variables value is %NORMAL. If this statements execution takes place within a form, and the record addition fails, the %STATUS variables value is %FAILURE, and IAF displays an error message. For details on streams and user buffers, refer to the discussion of record streams and buffer management in the IAF Users Guide.
database_handle

In the first syntax above, this is the handle for the database that holds the table to which to add a record. You must include a database handle only if you have invoked multiple databases, and the specified table does not exist in the current default database.
table_name

In the first syntax above, this is the name of the table to which to add the record. Statements that write to the user buffer of a tables primary stream include: an INPUT_BLOCK statement whose target is a table field. a CHECK_DOMAIN statement whose target is a table field. a table field specification on the left side of an assignment. For example:

Language Statements IAF 8.0 DML

6-25

ADD TO

SALES_ORDER_LINES(VALUE) = #CALC_VALUE

For details on the INPUT_BLOCK statement, refer to this manuals BLOCKS AND BLOCK QUALIFIERS chapter. For details on the CHECK_DOMAIN statement, refer to its description in this chapter.
#variable_name

In the second syntax on the preceding page, this is the name of a variable that contains the name of the table to which to add the record. Optionally, a database handle may precede the table name (see the description of database_handle above for details).
NOTES:

Executing the CLEAR_BUFFER statement prior to executing the ADD TO statement ensures that fields that have not received an explicit value in a newly added record are blank. Implicit or explicit execution of the CLEAR_BUFFER statement must take place prior to loading the fields to achieve this effect. IAF implicitly executes a CLEAR_BUFFER statement as the result of executing an INPUT_BLOCK or CHECK_DOMAIN statement that includes the /NEW qualifier. If the last statement on a form including the /REPEAT qualifier is an ADD TO statement, IAF implicitly executes a CLEAR_BUFFER statement. In the absence of an implicit or explicit CLEAR_BUFFER statement, the data values that are currently in the given user buffer remain available. Upon executing the ADD TO statement, IAF leaves the new record in the user buffer for subsequent access. Therefore, it is unnecessary to retrieve the new record via the CHECK_DOMAIN or FIND statement.

Example
CLEAR_BUFFER STOCK_MOVEMENTS STOCK_MOVEMENTS(WAREHOUSE_CODE)=PARTS(WAREHOUSE_CODE) STOCK_MOVEMENTS(PART_CODE)=PARTS(PART_CODE) STOCK_MOVEMENTS(QUANTITY)=#INPUT_QTY ! Place the data in the user buffer. ADD TO STOCK_MOVEMENTS ! Add the record to the STOCK_MOVEMENTS table.

Related Topics
The following references contain information pertaining to the ADD TO statement: This chapters discussions of the CLEAR_BUFFER, CHECK_DOMAIN, and FIND statements.

6-26

Language Statements IAF 8.0 DML

ADD TO

The discussion of the /REPEAT form qualifier in this manuals FORMS AND FORM QUALIFIERS chapter. The discussion of the /TARGET, /DOMAIN, and /NEW input block qualifiers in this manuals BLOCKS AND BLOCK QUALIFIERS chapter. The discussion of the %STATUS special variable in this manuals SPECIAL VARIABLES AND VALUE SYMBOLS chapter. The discussion of record streams and buffer management in the IAF Users Guide. The discussion of System Customization Variables (SCV) in the IAF guide that applies to your operating system.

Qualifiers
/NOERROR

Supresses the display of any error messages that occur during the ADD TO operation. Without this qualifier, if the record is a duplicate, a duplicate record error message will be displayed. You must check the %STATUS special variable after the ADD TO to determine it succeeded or failed. Examples
ADD TO CUSTOMERS /NOERROR IF (%STATUS <> %SUCCESS) ERROR /TEXT_ONLY ERROR_TEXT(%STATUS) ENDIF

Language Statements IAF 8.0 DML

6-27

ADD USER_ROLE

ADD USER_ROLE
Syntax
ADD USER_ROLE "user_id:role_name"

Category
Program flow

Description
This command adds the requested role to the specified user into the current database. user_id This is the user for which the specified role name will be added. role_name This is a string that represents the role to be added to the specified user into the current database. The maximum number of roles to be assigned to a user is fifty; but it can be assigned one at a time. GSRI will generate an error message if a user exceeds maximum number of roles assigned to him.

Example
ADD USER_ROLE "dinats:DEV"

Adds role DEV to dinats.

6-28

Language Statements IAF 8.0 DML

Archive

Archive
Syntax
ARCHIVE [DBMS] [{FROM|SOURCE}] from_database_handle [{TO|TARGET}] to_database_handle & [/COMMIT_RATE=commit_rate] [/FAILURE=(failure_dml)] [/LOG=log_file_specification [/NOLOG] [/NORESTART] [/NOSTATUS] [/NOVERBOSE] [/NOVERIFY] [/RESTART] [/STATUS] [/SUCCESS=(success_dml)] [/RESTART] & [/VERBOSE] [/VERIFY]

Category
Data Access

Description
This statement causes all marked rows in all archivable tables within the source database to be copied to the same named tables in the target database, then deleted from the source database. Both databases must have already been invoked before this statement is executed. The source and target databases must not be the same database. The metadata for the tables must be identical in both databases.

Language Statements IAF 8.0 DML

6-29

Archive

Qualifiers
The following qualifiers are valid for use with the ARCHIVE statement:
/FAILURE=(dml_statement)

This qualifier allows you to specify a DML statement that IAF is to execute if the archiving procedure fails.
/SUCCESS=(dml_statement)

This qualifier allows you to specify a DML statement that IAF is to execute if the archiving procedure succeeds.
/[NO]RESTART

If this qualifier is specified, IAF will first determine if an archive transfer is currently in progress. If /RESTART is specified and there is an unfinished data transfer outstanding, that transfer will be resumed. Otherwise an error message will be generated. If /NORESTART (the default) is specified and there is no unfinished transfer outstanding, then a new transfer session will be started. Attempts to start a new archive session when another is still in progress will result in an error message.
/[NO]VERIFY

This qualifier specifies whether additional checking is to be performed prior to starting the transfer of archived data. If /VERIFY (the default) is specified, then IAF will check that each archivable table in the source database exists in the target database. The system will also check that every column in an archivable source table has a corresponding column in the target table.
/[NO]VERBOSE

This qualifier allows you to specify the level of progress messages to be produced. /VERBOSE outputs full details about the archiving session to the message area of the screen. /NOVERBOSE (default) results in the only summary and error messages being displayed.

6-30

Language Statements IAF 8.0 DML

ASSERT

ASSERT
Syntax
ASSERT (condition_expression) [/MSG=""]

Category
Miscellaneous

Description
This statement is used to assert that an expression is TRUE. The expression is evaluated. If the result is TRUE, execution continues. If the result is FALSE, ASSERT displays the optional status message, and then exits with a %ASSERT_FAILURE condition value. The statement:
ASSERT (expression)

is equivalent to the following DML:

IF (NOT (expression)) EXIT (%ASSERT_FAILURE) END_IF

Qualifiers
/MSG="message"

This optional qualifier specifies a string to be displayed as a status message if the condition expression is FALSE.

Example 1
PROCEDURE_FORM TEST_ADDITION #A = 1 #B = 2 #C = #A + #B ASSERT (#C = 3) /MSG="Simple addition failed" END_FORM

Language Statements IAF 8.0 DML

6-31

ASSERT

Related Topics
The following references contain information pertaining to the ASSERT statement: This chapter's discussion of the ASSERT, ASSERT_EQUAL, ASSERT_FAIL and RUN_TESTS statements. The discussion of the special value symbol %ASSERT_FAILURE in the "Special Variables and Value Symbols" Chapter of this manual.

6-32

Language Statements IAF 8.0 DML

ASSERT_EQUAL

ASSERT_EQUAL
Syntax
ASSERT_EQUAL (expected_expression) (actual_expression) [/MSG=""]

Category
Miscellaneous

Description
This statement is used to assert that two expressions are equal. The expressions are evaluated and compared. If they are equal, execution continues. If they are not equal, a status message is displayed and the form exits with a %ASSERT_FAILURE condition value.

Qualifiers
/MSG="string"

This optional qualifier can be used to specify a string to be appended to the status message displayed if the two expressions are not equal. When this qualifier is used, the format of the status message is:
ASSERT_EQUAL Failed, Expected: "<value1>", Actual: "<value2>", Msg: "string" %DMRMAN-E-ASSERT_FAILURE, Assertion Failure

When this qualifier is not used, the format of the status message is:
ASSERT_EQUAL Failed, Expected: "<value1>", Actual: "<value2>" %DMRMAN-E-ASSERT_FAILURE, Assertion Failure

Example 1
#COUNT = 2 ASSERT_EQUAL (3) (#COUNT)

Produces the following:

ASSERT_EQUAL Failed, Expected: "3", Actual: "2" %DMRMAN-E-ASSERT_FAILURE, Assertion Failure

Language Statements IAF 8.0 DML

6-33

ASSERT_EQUAL

Example 2
Assume a STREAM, STR, with 3 records:
#COUNT = 0 WHILE ( 1 ) FETCH STR /FAILURE = (CONTINUE OUT) #COUNT = #COUNT + 1 END_WHILE ASSERT_EQUAL (3) (#COUNT) /MSG="Bad record count"

If only 2 records exist on the stream, the following is generated:

ASSERT_EQUAL Failed, Expected: "3", Actual: "2", Msg: "Bad record count" %DMRMAN-E-ASSERT_FAILURE, Assertion Failure

Related Topics
The following references contain information pertaining to the ASSERT statement: This chapter's discussion of the ASSERT, ASSERT_EQUAL, ASSERT_FAIL and RUN_TESTS statements. The discussion of the special value symbol %ASSERT_FAILURE in the "Special Variables and Value Symbols" Chapter of this manual.

6-34

Language Statements IAF 8.0 DML

ASSERT_FAIL

ASSERT_FAIL
Syntax
ASSERT_FAIL [/MSG="string"]

Category
Miscellaneous

Description
This statement is used to assert that a failure has occurred. The optional status message is displayed and the form exits with a %ASSERT_FAILURE condition value.

Qualifiers
/MSG="string"

This optional qualifier specifies a string to be displayed as a status message. When this qualifier is used, the following is displayed:
ASSERT_FAIL: "string" %DMRMAN-E-ASSERT_FAILURE, Assertion Failure

When this qualifier is not used:

%DMRMAN-E-ASSERT_FAILURE, Assertion Failure

Example
PROCEDURE_FORM TEST_GOTO GOTO PASS BEGIN_BLOCK FAIL ASSERT_FAIL /MSG="Simple GOTO FAILED" END_BLOCK BEGIN_BLOCK PASS EXIT (%SUCCESS) END_BLOCK END_FORM

Language Statements IAF 8.0 DML

6-35

ASSERT_FAIL

Related Topics
The following references contain information pertaining to the ASSERT statement: This chapter's discussion of the ASSERT, ASSERT_EQUAL, ASSERT_FAIL and RUN_TESTS statements. The discussion of the special value symbol %ASSERT_FAILURE in the "Special Variables and Value Symbols" Chapter of this manual.

6-36

Language Statements IAF 8.0 DML

BEGIN_DISABLE_TRIGGER

BEGIN_DISABLE_TRIGGER
Syntax
BEGIN_DISABLE_TRIGGER

Category
Program flow

Description
This statement disables update triggers until execution of an END_DISABLE_TRIGGER statement takes place. For details regarding update triggers, refer to the discussion of the Data Definition Editor in the IAF System Reference Manual. For details regarding the END_DISABLE_TRIGGER statement, refer to its description in this chapter.

Example
BEGIN_DISABLE_TRIGGER MEMBERS(MEMBER_ID)=#TEST_ID END_DISABLE_TRIGGER

The result of this example is that, even if there is an update trigger for the MEMBERS(MEMBER_ID) field, it will not be activated as a result of the assignment statement following the BEGIN_DISABLE_TRIGGER statement.

Related Topics
The following references contain information pertaining to the BEGIN_DISABLE_TRIGGER statement. This chapters discussion of the END_DISABLE_TRIGGER statement. The discussion of update triggers in the IAF System Reference Manual section pertaining to the Data Definition Editor.

Language Statements IAF 8.0 DML

6-37

BEGIN_SIGNAL_TO_STATUS

BEGIN_SIGNAL_TO_STATUS
Syntax
BEGIN_SIGNAL_TO_STATUS

Category
Program flow

Description
This statement causes IAF to begin trapping signaled errors to the %STATUS special variable. By default, signaled errors (i.e. errors that are fatal to a DML program) do not affect %STATUS. When executing this statement, IAF sets %STATUS to %NORMAL. If a statement executed in the current form after this statement and before the END_SIGNAL_TO_STATUS statement causes a fatal error, %STATUSs value changes. The BEGIN_SIGNAL_TO_STATUS statement cannot trap a %DEADLOCK signal. However, the PERFORM statements /NODEADLOCK_EXIT qualifier can. The BEGIN_SIGNAL_TO_STATUS statement affects only the form that executes it. Forms that the current form performs signal errors instead of trapping them to %STATUS. However, once a called form exits and returns control to the form that executed the BEGIN_SIGNAL_TO_STATUS statement, the PERFORM statement converts the signal to an error in %STATUS. The BEGIN_SIGNAL_TO_STATUS statements scope is one form. IAF stops trapping signaled errors to %STATUS upon exiting the form.

6-38

Language Statements IAF 8.0 DML

BEGIN_SIGNAL_TO_STATUS

Example
PROCEDURE_FORM CHECK_FOR_FILE (#FILE_NAME) ! This routine returns %NORMAL if the given file exists, ! and %FAILURE if it does not. BEGIN_SIGNAL_TO_STATUS OPEN_TEXT #FILE_NAME AS TEST_TAG END_SIGNAL_TO_STATUS IF (%STATUS=%NORMAL) CLOSE_TEXT TEST_TAG EXIT (%NORMAL) ELSE EXIT (%FAILURE) END_IF END_FORM

Related Topics
The following references contain information pertaining to the BEGIN_SIGNAL_TO_STATUS statement: This chapters discussions of the END_SIGNAL_TO_STATUS and PERFORM statements. The discussion of the %STATUS special variable in this manuals SPECIAL VARIABLES AND VALUE SYMBOLS chapter.

Language Statements IAF 8.0 DML

6-39

CALL

CALL
Syntax
CALL routine_name [(argument1[,argument2[,...]])]

Category
Program flow

Description
This statement executes the specified external routine. In order for the CALL statement to call an external routine, you must compile and link the routine via the methods described in the IAF guide that applies to your operating system. IAF also requires you to declare the specified routine via the EXTERNAL statement prior to using the CALL statement to execute the routine. The EXTERNAL statement identifies the file in which the specified routine resides. The compiler checks that each CALL statement has a matching EXTERNAL statement. Executing the CALL statement within a form causes IAF to place the external routines return status in the %STATUS special variable.
routine_name

This is the name of the external routine to execute and must be a name that a preceding EXTERNAL statement declares.
(argument1[,argument2[,...]])

This is one or more arguments to pass to the external routine. The EXTERNAL statement that declares the external routine also defines the passing mechanism (descriptor, reference, or value) for any arguments that the routine accepts. IAF applies the following rules when passing arguments to external routines: Single variables, table fields, and DML parameters are implicitly read-write. Otherwise, all other arguments are read-only. In order for an external routine to modify an argument that the CALL statement passes to it, the argument must be a variable, table field, or

6-40

Language Statements IAF 8.0 DML

CALL

DML parameter, and the passing mechanism that the EXTERNAL statement declares for the argument must be either a reference or descriptor.
NOTE:

You can enclose a single variable, table field, or DML parameter in parentheses (nested within the parentheses that are part of the CALL statements standard syntax) to change it from a read/write argument to a read-only argument. Unless conditions are prohibitive, this practice is advisable as it avoids any unnecessary write to the given variable, table field, or DML parameter. By following this practice, you can obtain the data that the variable, table field, or parameter contains without writing back any changes to the variable, table field, or parameter. If the argument is a read/write argument, the write occurs after the routines completion regardless of whether the routine modified the argument.

Examples
CALL CHECK_DIGIT (#CUSTOMER_ID) CALL SALES_PREDICTION (#RESULT, #GROWTH_RATE, & SALES_PEOPLE(TOTAL_SALES), #MONTHS, & (SALES_PEOPLE(SALES_PERSON))) CALL NTH_ROOT(#RESULT,(#VAL),(#EXP))

Related Topics
The following references contain information pertaining to the CALL statement: This chapters discussion of the EXTERNAL statement. The discussion of the %STATUS special variable in this manuals SPECIAL VARIABLES AND VALUE SYMBOLS chapter. The discussion of building and using external routines in the IAF guide that applies to your operating system.

Language Statements IAF 8.0 DML

6-41

CALL_WEB_SERVICE

CALL_WEB_SERVICE
Syntax
CALL_WEB_SERVICE & [/ACTION=action] & [/OPERATION=operation] & [/PARAMETER=(NAME=name, TYPE=type, SOURCE=source, TARGET=target)] & [/NAMESPACE=namespace] & [/URL=url] & [/RESPONSE=response] & [/RESULT=(NAME=name, TYPE=type, TARGET=target)]

Category
Program flow

Description
This statement permits DML programs to call Web Services. Each of the qualifier values can be a quoted literal, variable, specialvariable, function, table-field or expression. Action, operation, name and response are XML tags. Type specifies the datatype name required by the Web Service. The content of value is a parameter value that is passed to the Web Service. The DML language treats all of these qualifier values as text strings and otherwise passes them as-is to the Web Service without imposing any particular interpretation on their content. Target specifies a variable or table-field in which to place the result. The parameter qualifier can be repeated as many times as necessary to pass all parameters. No particular limit is imposed on the number of parameters that may be passed.

Qualifiers
/FAULT_ACTOR If a fault occurs, this qualifier can be used to receive the fault actor. A null string is returned when no fault occurs.
6-42 Language Statements IAF 8.0 DML

CALL_WEB_SERVICE

/FAULT_CODE If an error occurs, this qualifier can be used to receive the fault code. A null string is returned when no fault occurs. /FAULT_STRING If an error occurs, this qualifier can be used to receive the fault string. A null string is returned when no fault occurs.

Examples
Call_Web_Service & /Action="http://www.rossinc.com/cws" & /Namespace="http://www.rossinc.com/dml/cws/example/" & /Operation="SwitchWebService" & /Parameter=( Name="strCase", & Type="string", & Value=#Case ) & /Parameter=( Name="strEncrypted", & Type="string", & Value=#Encrypted ) & /Parameter=( Name="strSignature", & Type="string", & Value=#Signature ) & /Response="SwitchWebServiceResponse" & /Result=( Name="SwitchWebServiceResult", & Type="string", & Target=#Tesult ) & /Url="http://www.rossinc.com/dml/cws/example.asmx" if (%Status <> %Success) & Error /Text_Only ("Web service error status=" & %Status)

Language Statements IAF 8.0 DML

6-43

CASE, BEGIN_CASE, CASE ELSE, and END_CASE

CASE, BEGIN_CASE, CASE ELSE, and END_CASE

Syntax
BEGIN_CASE (initial_expression) CASE expression[,expression[,...]]

or
CASE operator expression

or
CASE expression_a TO expression_b

or
CASE ELSE END_CASE

Category
Program flow

Description
This set of language constructs enables you to specify an initial expression that IAF is to evaluate against a list of expressions to determine the processing that is to take place. You specify the initial expression via the BEGIN_CASE statement. You specify the expressions against which IAF is to evaluate the initial expression via the CASE statement. Additionally, you can specify a single CASE ELSE statement in case no other CASE statements evaluate to true. You can include any number of CASE statements within a given BEGIN_CASE/END_CASE construct. Upon encountering a BEGIN_CASE statement, IAF evaluates the initial expression that the BEGIN_CASE statement specifies, and as a result, obtains a constant initial value. IAF then sequentially examines each CASE statement included within the given BEGIN_CASE/END_CASE construct. If a CASE statements expression evaluates to true for the initial value that the given BEGIN_CASE statement specifies, IAF ends the examination of the CASE statements, executes the DML code

6-44

Language Statements IAF 8.0 DML

CASE, BEGIN_CASE, CASE ELSE, and END_CASE

associated with the given CASE statement, and transfers program control to the END_CASE statement. CASE statement expressions can overlap in ranges of true values (i.e. more than one CASE statement expression can evaluate to true for the initial value that the BEGIN_CASE statement specifies). However, IAF executes only the DML code associated with the first CASE statement whose expression evaluates to true for the initial value. If no CASE statement expression evaluates to true for the initial value, and a CASE ELSE statement is present, IAF executes the DML code associated with the given CASE ELSE statement. Otherwise, program control transfers to the END_CASE statement. Every BEGIN_CASE statement must have a corresponding END_CASE statement. Additionally, you can nest a BEGIN_CASE/END_CASE construct within a given CASE statement.
BEGIN_CASE (initial_expression)

The BEGIN_CASE statement specifies the initial expression against which IAF is to evaluate the given case expressions. The initial expression can be any language construct that evaluates to a single value.
CASE expression[,expression[,...]]

CASE statements of this type specify one or more expressions that IAF is to evaluate and compare to the initial expression that the BEGIN_CASE statement specifies. IAF executes the DML code associated with a CASE statement in this format if any of the expressions it specifies is the first case expression whose value equals the value of the initial expression that the BEGIN_CASE statement specifies. A case expression can be any language construct that evaluates to a single value.
CASE operator expression

CASE statements of this type specify an operator and an expression which IAF appends to the initial expression that the BEGIN_CASE specifies to form an expression to evaluate as follows:
initial_expression operator expression

Language Statements IAF 8.0 DML

6-45

CASE, BEGIN_CASE, CASE ELSE, and END_CASE

If this formed expression is true, IAF executes the DML code associated with the CASE statement. The following table lists the operators that are valid for use with CASE statements of this type. Operator = <> <= >= < > equal to not equal to less than or equal to greater than or equal to less than greater than Operation

CASE expression_a TO expression_b

CASE statements of this type specify expressions delimiting an inclusive range of values. IAF executes the DML code associated with the CASE statement if the value of the initial expression that the BEGIN_CASE statement specifies falls within the inclusive range of values that the two expressions delimit.
CASE ELSE

This statement enables you to specify DML code that IAF is to execute if none of the preceding CASE statements have been true for the value of the initial expression that the BEGIN_CASE statement specifies. You may include a single CASE ELSE statement per BEGIN_CASE/END_CASE construct. IAF always evaluates the CASE ELSE statement to be true, and automatically executes the DML code associated with it. Therefore, place the CASE ELSE statement after the last CASE statement in the BEGIN_CASE/END_CASE construct.

Example
BEGIN_CASE (#A) CASE 1 PRINT #A is 1 CASE < (1-1) PRINT #A less than 0 CASE >= 100 PRINT #A greater than or equal to 100 CASE A,B,C,#B PRINT #A is A or B or C or equal to #B

6-46

Language Statements IAF 8.0 DML

CASE, BEGIN_CASE, CASE ELSE, and END_CASE

CASE x PRINT #A is a lowercase x CASE a TO z PRINT #A is a lowercase letter but not x CASE ELSE PRINT #A is something else END_CASE

Related Topics
The following reference contains information pertaining to the CASE, BEGIN_CASE, CASE ELSE, and END_CASE statements: The discussion of expressions in this manuals Expressions chapter.

Language Statements IAF 8.0 DML

6-47

CD

CD
Syntax
CD directory

Category
Miscellaneous

Description
This statement sets the users current working directory (aka default directory). See also the SET DEFAULT and SET WD statements.

6-48

Language Statements IAF 8.0 DML

CHECK_DOMAIN

CHECK_DOMAIN
Syntax
CHECK_DOMAIN [label_name] /TARGET=table_name(field_name) [/qualifiers]

or
CHECK_DOMAIN [label_name] /USING=table_name(field_name) [/qualifiers]

Category
Data access

Description
This statement facilitates implicit and explicit domain validation of data when no screen input or output is taking place. IAF determines the source data on which to perform the domain validation according to the following ordered steps. 1. IAF evaluates the condition expressions of any /SOURCE_IF qualifiers that the CHECK_DOMAIN statement includes until a condition expression is true, or there are no more /SOURCE_IF qualifiers to evaluate. If a /SOURCE_IF qualifiers condition expression is true, IAF performs the domain validation on the source data that the qualifier specifies, and performs no further /SOURCE_IF evaluations. If there are no /SOURCE_IF qualifiers, or no /SOURCE_IF qualifiers condition expression is true, IAF proceeds as indicated below. IAF performs the domain validation on the data that the /SOURCE qualifier specifies. If there is no /SOURCE qualifier, IAF proceeds as indicated below. IAF performs the domain validation on the data in the table field that the /USING qualifier specifies. If there is no /USING qualifier, IAF proceeds as indicated below. IAF performs the domain validation on the data in the table field that the /TARGET qualifier specifies.

2.

3.

4.

Language Statements IAF 8.0 DML

6-49

CHECK_DOMAIN

IAF determines the domain table against which to validate the source data according to the following ordered steps if a /DOMAIN qualifier is present. 1. IAF validates the source data against the data in the table field that links the table that the /DOMAIN qualifier specifies to the table that the /SOURCE_IF qualifier having the first true condition expression specifies. If the /SOURCE_IF qualifier having the first true condition expression does not specify a table field, IAF proceeds as indicated in step 3 below. If there are no /SOURCE_IF qualifiers, IAF proceeds as indicated in step 2 below. IAF validates the source data against the data in the table field that links the table that the /DOMAIN qualifier specifies to the table that the /SOURCE qualifier specifies. If there is no /SOURCE qualifier, or the /SOURCE qualifier does not specify a table field, IAF proceeds as indicated below. IAF validates the source data against the data in the table field that links the table that the /DOMAIN qualifier specifies to the the table that the /USING qualifier specifies. If there is no /USING qualifier, IAF proceeds as indicated below. IAF validates the source data against the data in the table field that links the table that the /DOMAIN qualifier specifies to the table that the /TARGET qualifier specifies.

2.

3.

4.

IAF determines the domain table against which to validate the source data according to the following ordered steps if no /DOMAIN qualifier is present. 1. IAF validates the source data against the data in the table field that the /USING qualifier specifies. If there is no /USING qualifier, IAF proceeds as indicated below. 2. IAF validates the source data against the data in the table field that the /TARGET qualifier specifies. IAF performs domain validation on all implicit and explicit domains related to a given CHECK_DOMAIN statement. If the source data exists in the domain table (i.e. the table that the /DOMAIN, /USING, or /TARGET qualifier specifies), IAF retrieves the matching record, thereby making its data available for subsequent use. If the CHECK_DOMAIN statement includes the /PROTECT qualifier, IAF retrieves records via a secondary stream, instead of the primary stream.

6-50

Language Statements IAF 8.0 DML

CHECK_DOMAIN

For details regarding the /PROTECT qualifier, refer to its description under this sections Qualifiers heading. For details on record streams, refer to the discussion of record streams and buffer management in the IAF Users Guide. If the CHECK_DOMAIN statement includes the /TARGET qualifier, IAF copies the source data into the table field that the /TARGET qualifier specifies. If any domain validation fails, IAF displays an error message on the screen. For details on domain validation results (i.e. success or failure), refer to the description of the /NEW qualifier under this sections Qualifiers heading.
label_name

This is an optional label to facilitate branching to the CHECK_DOMAIN statement.

Qualifiers
The following qualifiers are valid for use with the CHECK_DOMAIN statement:
/DOMAIN=table_name

This qualifier causes IAF to validate the domain that links the table that this qualifier specifies to the table field that the /SOURCE, /SOURCE_IF, /USING, or /TARGET qualifier specifies (refer to this sections Description heading). The CHECK_DOMAIN statement can include more than one /DOMAIN qualifier. IAF performs domain validation for each domain table specified. If no /DOMAIN qualifier is present, IAF validates the source data against the table that the /TARGET or /USING qualifier specifies. For details on the effect of using the /DOMAIN qualifier in conjunction with other CHECK_DOMAIN statement qualifiers, refer to this sections Description heading.
/ERROR=expression

This qualifier enables you to specify an error message that IAF is to display if any domain validation fails, thereby overriding the default error message that IAF would otherwise display.

/FAILURE=(dml_statement)

Language Statements IAF 8.0 DML

6-51

CHECK_DOMAIN

This qualifier enables you to specify a DML statement that IAF is to execute if any domain validation fails.
/NEW

This qualifier indicates that IAF is to reverse the domain validation. The following table illustrates the results of domain validation with and without the /NEW qualifier. /NEW NO NO YES YES Source data exists in domain table field YES NO YES NO SUCCESS FAILURE FAILURE SUCCESS Result

If /NEW is present, and the domain validation fails, IAF displays an error message, and fetches the matching record from the domain table.
/NOCLEAR_BUFFER

This qualifier indicates that IAF is not to clear the user buffer associated with the domain table if the domain validation fails. By default, if a domain validation fails, IAF executes an implicit CLEAR_BUFFER statement that clears all fields, except PID fields, in the user buffer associated with the domain table. For details regarding user buffers, refer to the IAF Users Guide.
/NOERROR

This qualifier indicates that IAF is not to display an error message if the domain validation fails. Normally, IAF displays an error message indicating the reason for the failure as the following example indicates:
No such DEPARTMENT in DEPARTMENTS

The /NOERROR qualifier disables this error display, thereby allowing you to display an alternate error message. For details on specifying an alternate error message, refer to this chapters description of the ERROR statement.
/OPTION=option_keyword

6-52

Language Statements IAF 8.0 DML

CHECK_DOMAIN

This qualifier allows you to override the default READ lock that IAF places on the records that the CHECK_DOMAIN statement retrieves. The following table lists and describes the effect of the lock option keywords that are available for use with the /OPTION qualifier. Option Keyword DOMAIN_LOCK_WRITE Effect This lock option causes IAF to immediately place a WRITE lock on the records that the CHECK_DOMAIN statement retrieves. By default, IAF promotes a records READ lock to a WRITE lock only if an attempt to write to the record is made. This option prevents other users from updating a given record for the duration of the stream and prevents deadlocks from occurring for records in high contention situations. This lock option causes IAF to place no locks on the records that the CHECK_DOMAIN statement retrieves. This option allows other users to access the records in the stream that the CHECK_DOMAIN statement creates. However, record updates that other users perform will not be visible to the process that executed the CHECK_DOMAIN statement.

DOMAIN_LOCK_NONE

For details regarding records streams, data locks, and data contention, refer to the IAF User Guide.

Language Statements IAF 8.0 DML

6-53

CHECK_DOMAIN

/PROTECT

This qualifier indicates that IAF is to create a secondary stream on which to perform the domain validation. By default, IAF performs domain validation on the primary stream associated with the table against which the source data is being validated (the domain table). Because a table can be associated with only one primary stream, performing domain validation on the primary stream overwrites any record that was in the user buffer associated with the primary stream. Performing the domain validation on a secondary stream leaves any record currently in the user buffer associated with the domain tables primary stream undisturbed, regardless of the result of the domain validation.
NOTE:

Using the /NEW and /PROTECT qualifiers together has a special effect. When used together, these qualifiers act as previously described, unless the source data exists in the domain table field, in which case, IAF compares the matching domain table record with the record currently in the user buffer. If the records are the same, IAF considers the domain table record not to have been found. Using the /NEW and /PROTECT qualifiers together is useful when changing the value of a secondary unique index. When used in this way, the domain validation fails if IAF finds the value of the secondary index on another record in the domain table, but succeeds if IAF finds the value of the secondary index in the record currently in the user buffer.
/SOURCE=expression

If there are no /SOURCE_IF qualifiers, this qualifier indicates the data that IAF is to validate. Otherwise, this qualifier indicates the data that IAF is to validate if no /SOURCE_IF qualifiers condition expression is true. The /SOURCE expression can be any valid DML data expression (i.e. a quoted literal, table field, variable, or any combination thereof). If the CHECK_DOMAIN statement does not include a /SOURCE qualifier, IAF validates the data that the /USING or /TARGET qualifier specifies. For details on the effect of using the /SOURCE qualifier in conjunction with other CHECK_DOMAIN statement qualifiers, refer to this sections Description heading.
/SOURCE_IF=(condition_expression), source_expression

If the CHECK_DOMAIN statement includes one or more /SOURCE_IF qualifiers, IAF evaluates each ones condition expression until a condition expression is true or there are no more /SOURCE_IF condition expressions to evaluate. If a /SOURCE_IF condition expression is true,
6-54 Language Statements IAF 8.0 DML

CHECK_DOMAIN

IAF performs the domain validation on the data that the qualifier specifies, and performs no further /SOURCE_IF evaluations. Otherwise, IAF performs the domain validation on the data that the /SOURCE qualifier specifies, if present, or the data that the /USING or /TARGET qualifier specifies, if there is no /SOURCE qualifier. For details on the effect of using the /SOURCE_IF qualifier in conjunction with other CHECK_DOMAIN statement qualifiers, refer to this sections Description heading.
/SUCCESS=(dml_statement)

This qualifier enables you to specify a DML statement that IAF is to execute if all applicable domain validations succeed.
/TARGET=table_name(field_name)

This qualifier indicates the table field in which IAF is to place the source data if the source data exists in the domain table. Additionally, if no other qualifier (i.e. /SOURCE or /SOURCE_IF) is providing the source data to validate, IAF validates the data in the table field that the /TARGET qualifier specifies. The table that the /TARGET qualifier specifies can also be the domain table as indicated under this sections Description heading. For details on the effect of using the /TARGET qualifier in conjunction with other CHECK_DOMAIN statement qualifiers, refer to this sections Description heading. Note that the /TARGET qualifier and the /USING qualifier are mutually exclusive.
/USING=table_name(field_name)

If no other qualifier (for example; /SOURCE or /SOURCE_IF) is providing the source data to validate, IAF validates the data in the table field that the /USING qualifier specifies. Additionally, the table that the /USING qualifier specifies can also be the domain table as indicated under this sections Description heading. For details on the effect of using the /USING qualifier in conjunction with other CHECK_DOMAIN statement qualifiers, refer to this sections Description heading. Note that the /USING qualifier and the /TARGET qualifier are mutually exclusive.

Examples
CHECK_DOMAIN GET_CUSTOMER /SOURCE=#CUSTOMER & /TARGET=CUSTOMERS(CUSTOMER_ID) & /ERROR=Customer deleted! /FAILURE=(EXIT(%FAILURE))

This example validates the data in the #CUSTOMER variable against the CUSTOMERS(CUSTOMER_ID) table field. If the CUSTOMERS table contains a record for which the value of the CUSTOMER_ID field equals

Language Statements IAF 8.0 DML

6-55

CHECK_DOMAIN

the value of the #CUSTOMER variable, IAF fetches the record and places it in the user buffer associated with the CUSTOMERS tables primary stream. Otherwise, IAF displays Customer deleted! on the screen and exits the current form with a %FAILURE status.
CHECK_DOMAIN /SOURCE=SALES(CUSTOMER_ID) /TARGET=INVOICES(CUSTOMER_ID) & /DOMAIN=CUSTOMERS /ERROR=Invalid Customer ID

Assuming that the CUSTOMERS table has a CUSTOMER_ID field, this example validates the data in the SALES(CUSTOMER_ID) table field against the CUSTOMERS(CUSTOMER_ID) table field. If the source data exists in the CUSTOMERS(CUSTOMER_ID) table field, IAF writes the given customer ID to the INVOICES(CUSTOMER_ID) table field, and fetches the matching record from the CUSTOMERS table and places it in the user buffer associated with the CUSTOMERS tables primary stream. Otherwise, IAF displays Invalid Customer ID on the screen.
CHECK_DOMAIN /SOURCE=#CUST_ID /USING=SALES(CUSTOMER_ID) & /DOMAIN=CUSTOMERS /NEW & /ERROR=Customer already exists. & /SUCCESS=(PERFORM ADD_RECORD)

This example validates the data in the #CUST_ID variable against the CUSTOMERS(CUSTOMER_ID) table field using the attributes of the SALES(CUSTOMER_ID) table field. Because of the /NEW qualifier, if the source data does not exist in the CUSTOMERS(CUSTOMER_ID) table field, IAF executes the statement that the /SUCCESS qualifier specifies (i.e. PERFORM ADD_RECORD). Otherwise, IAF displays Customer already exists. and fetches the matching record from the CUSTOMERS table.

Related Topics
The following references contain information pertaining to the CHECK_DOMAIN statement: The discussion of input blocks and input block qualifiers in this manuals BLOCKS AND BLOCK QUALIFIERS chapter. The discussion of domains in the IAF Users Guide. The discussion of record streams and buffer management in the IAF Users Guide.

6-56

Language Statements IAF 8.0 DML

CLEAR_ARRAY

CLEAR_ARRAY
Syntax
CLEAR_ARRAY #array()

Category
Miscellaneous

Description
This statement causes the specified array to be cleared. The cleared array has zero elements.

Examples
Clear_Array #DmlProgram #DmlProgram(1) = "Procedure_Form Main(#A)" #DmlProgram(2) = "Print #A" #DmlProgram(3) = "End_Form" Set Debug On Perform/Array #DmlProgram Main("Hello")

Language Statements IAF 8.0 DML

6-57

CLEAR_BUFFER

CLEAR_BUFFER
Syntax
CLEAR_BUFFER [database_handle.]table_name

or
CLEAR BUFFER #variable_name

Category
Data access

Description
This statement clears all non-PID field entries in the user buffer associated with the given table, and leaves the tables PID field(s) untouched. For details regarding PID fields, refer to the IAF guide that applies to the database engine in use. IAF implicitly executes a CLEAR_BUFFER statement when a tables primary or secondary stream ends. However, you can use the /NOCLEAR_BUFFER qualifier to disable IAFs default clearing effect. For details on the /NOCLEAR_BUFFER qualifier, refer to its description in this manuals BLOCKS AND BLOCK QUALIFIERS chapter and this chapters description of the CHECK_DOMAIN statement.
database_handle

In the first syntax above, this is the handle for the database in which the table whose buffer IAF is to clear resides. It is necessary to include a database handle only if you have invoked multiple databases, and the specified table does not exist in the current default database.
table_name

In the first syntax above, this is the name of the table whose user buffer IAF is to clear.
#variable_name

In the second syntax above, this is the name of a variable that contains the name of the table whose user buffer IAF is to clear. Optionally, a database handle may precede the table name (see the description of database_handle above for details).

6-58

Language Statements IAF 8.0 DML

CLEAR_BUFFER

Examples
CLEAR_BUFFER CUSTOMERS CLEAR_BUFFER SALES_ORDERS #NAME=ORDERS.SALES_ORDER_LINES CLEAR_BUFFER #NAME

Related Topics
The following references contain information pertaining to the CLEAR_BUFFER statement: This chapters discussions of the CHECK_DOMAIN, FETCH, and FIND IN statements. The discussion of the /NOCLEAR_BUFFER block qualifier in this manuals BLOCKS AND BLOCK QUALIFIERS chapter. The discussion of record streams and buffer management in the IAF Users Guide. The discussion of primary identifiers (PIDs) in the IAF guide that applies to your database engine.

Language Statements IAF 8.0 DML

6-59

CLI

CLI
Syntax
CLI [/qualifiers] command_expression

Category
Miscellaneous

Description
The CLI (Command Language Interpreter) statement causes IAF to pass the given command expression to the operating system, and is the vehicle by which you can execute operating system commands from within IAF. Executing the CLI statement within a form causes IAF to place the operations completion status in the %STATUS special variable.
command_expression

This is an expression indicating the operating system specific command to execute.

Qualifiers
The following qualifiers are valid for use with the CLI statement:
/CLIENT

This qualifier applies only to IAF Thin Client. It indicates that the given command is to execute on the client side, not the server side.
/NOERASE

This qualifier prevents IAF from clearing the screen before executing the given command. This qualifier is intended for use with operating system commands that perform no output to the screen.

6-60

Language Statements IAF 8.0 DML

CLI

/NOWAIT

This qualifier applies only to IAF Thin Client and IAF Client for Windows Professional (GCW Pro). It indicates that IAF should not wait for the CLI command to complete before processing the next DML statement.
/PAUSE

This qualifier causes IAF to pause and display the message Enter Return to Continue after executing the given command. This qualifier provides for viewing any output that the operating system command generates.
/WAIT

This qualifier applies only to IAF Thin Client and IAF for Windows Professional (GCW Pro). It indicates that IAF should wait for the CLI command to complete before processing the next DML statement.

Related Topics
The following references contain information that pertains to the CLI statement: This chapters discussions of the DCL and $ (dollar sign) statements. The discussion of the %STATUS special variable in this manuals Special Variables And Value Symbols chapter.

Language Statements IAF 8.0 DML

6-61

CLOSE

CLOSE
Syntax
CLOSE datafile_handle

Category
Data access

Description
This statement dynamically closes an unrelated table file that was previously opened via the DML OPEN statement, and is valid for use only with unrelated RMS table files when running IAF on OpenVMS.
datafile_handle

This is the handle of the unrelated table file to close, and is the handle that the OPEN statement specified when it opened the file.

Examples
OPEN SALES_ORDERS AS ORDERS ! Opens an unrelated table file . . CLOSE ORDERS ! Closes an unrelated table file

Related Topics
The following references contain information pertaining to the CLOSE statement: This chapters discussion of the OPEN statement. The discussion regarding unrelated table files in the Guide to Using IAF with RMS.

6-62

Language Statements IAF 8.0 DML

CLOSE_TABS

CLOSE_TABS
Syntax
CLOSE_TABS [/optional qualifiers]

Optional Qualifiers
/IAF_ONLY

Close only the tabs the correspond to running IAF programs and any cached gem_ui_servers.
/HTML_ONLY

Close only the tabs that correspond to HTML URLs. If neither qualifier is specified, all tabs are closed. /IAF_ONLY and /HTML_ONLY are mutually exclusive.

Description
The CLOSE_TABS statement is an iBrowser-only addition to the IAF DML language. When executed, it closes the currently-opened tabs. When closing IAF tabs, any cached gem_ui_server processes are also terminated. The only exception is that the tab for the program that executes the CLOSE_TABS statement is not closed.

Corresponding UIDL
TAG Remove Tabs: <RT>

Description
This tag indicates that existing tabs should be closed. It is a child of the UIDL tag.

Language Statements IAF 8.0 DML

6-63

CLOSE_TABS

Attributes
Attribute G H Definition To close just the IAF tabs To close just the HTML tabs

Syntax
<RT G=True H=True/>

6-64

Language Statements IAF 8.0 DML

CLOSE_TEXT

CLOSE_TEXT
Syntax
CLOSE_TEXT tag

Category
Text file management

Description
This statement indicates that IAF is to close the given text file that was previously opened via the OPEN_TEXT statement.
tag

This is the handle of the text file to close, and is the handle that the OPEN_TEXT statement specified when it opened the file.

Examples
CLOSE_TEXT ADDRESS CLOSE_TEXT PHONE_LIST

Related Topics
The following references contain information pertaining to the CLOSE_TEXT statement: This chapters discussions of the OPEN_TEXT, READ_LINE, REWIND_TEXT, WRITE, and WRITE_LINE statements.

Language Statements IAF 8.0 DML

6-65

COCALL

COCALL
Syntax
[return_value=] COCALL argument2, )] object_handle.method [(argument1,

or
[return_value=] COCALL argument2, )] #variable_obj.method [(argument1,

or
COCALL object_handle.method [(argument1, argument2, )]=assign_expression

or
COCALL #variable_obj.method [(argument1, argument2, )]=assign_expression

Category
Utility

Description
COCALL is used to call a method of the COM/Active X object and to get or set properties. A COCALL statement with a return value assignment is analogous to a function call. A COCALL statement without a return value assignment is analogous to a procedure call. COCALLs that have parentheses without arguments behave the same as COCALLs with no parentheses. The [out] arguments and assign_expressions are translated, as best as possible, into VARIANT-style types. Likewise, the [in] arguments and return_value are translated, as best as possible, into IAF data types. This statement also provides the capability of invoking a COCALL within a COCALL, for example:
[return_value=] COCALL object_handle.method (COCALL object_handle.method & [(argument1, argument2, )])

or

6-66

Language Statements IAF 8.0 DML

COCALL

[return_value=] COCALL #variable_obj1.method (COCALL #variable_obj2.method & [(argument1, argument2, )])

This statement also provides a way to "set" and "get" attributes/properties of the COM object. An example of the statement's syntax is as follows: For GETing,
#GET= COCALL object_handle.property_name [(argument1, argument2, )]

or for SETing,
COCALL object_handle.property_name [(argument1, argument2, )] = #SET

object_handle

The COM object instantiation previously created by the COCREATE statement or returned from a previous COCALL statement may be either a Handle or Gem variable. See the object_handle definition under the COCREATE section.
#variable_obj, #variable_obj1, #variable_obj2

These are the names of the variables that indicate references to the instantiated COM objects. method The name of the member function of the interface inside of a COM object. (argument1, argument2, ) The arguments in the COCALL statement conform to IAF datatypes. The arguments can be passed either by reference [in][out] or by value [in]. Optional arguments, that is, arguments without assigned values are possible if they are defined in the method specification. Both the required and optional arguments mentioned so far, are called positional arguments. COM objects can also support named arguments that can be placed anywhere in a method's argument list and are identified by a name that has meaning to the method itself. For example,
ComObj1.FindConnection(IPCName="Rush", UserName="Videos", Password="IAF").

return_value

Language Statements IAF 8.0 DML

6-67

COCALL

The return_value datatypes conform to IAF datatypes. return_value is utilized by function-like methods and Property GETting COCALL statements. assign_expression assign_expressions are values as defined in the Expressions chapter of the IAF Data Manipulation Language manual. assign_expressions are utilized in the Property SETting COCALL statements.

Example 1
FORM EXAMPLE_2 /ROW=1 /COL=1 /WIDTH=8 /HEIGHT=25

! Execute a COCALL statement without any arguments. ! This example invokes a word application. It opens the ! workbook by executing a COCALL with no arguments.

COCREATE "Word.Application" AS MYWORD #WB = COCALL MYWORD.Workbooks COCALL #WB.Add

END_FORM

Example 2
FORM EXAMPLE_3 /ROW=1 /COL=1 /WIDTH=8 /HEIGHT=25 ! Execute a COCALL statement with positional arguments. ! Start word application. Move the window using positional ! arguments. COCREATE "Word.Application" AS MYWORD

! Set the positional arguments. #DIM1 = 150 #DIM2 = 20

! Invoke the MOVE method with positional arguments. COCALL MYWORD.Move(#DIM1, #DIM2)

END_FORM

6-68

Language Statements IAF 8.0 DML

COCALL

Example 3
FORM EXAMPLE_4 /ROW=1 /COL=1 /WIDTH=8 /HEIGHT=25

! Execute a COCALL statement with input parameters. ! Start word application. Move the window using input ! parameters. COCREATE "Word.Application" AS MYWORD

! Invoke the MOVE method with input parameters. COCALL MYWORD.Move(150, 20)

END_FORM

Example 4
FORM EXAMPLE_5 /ROW=1 /COL=1 /WIDTH=8 /HEIGHT=25

! Execute a COCALL statement with combination of parameters. COCREATE "Word.Application" AS MYWORD

! Set the positional argument. #DIM1 = 20

! Invoke the MOVE method. COCALL MYWORD.Move(150, #DIM1)

END_FORM

Example 5
FORM EXAMPLE_6 /ROW=1 /COL=1 /WIDTH=8 /HEIGHT=25

! Execute a COCALL statement to SET a property. ! Start word application. COCREATE "Word.Application" AS MYWORD

! SET property. COCALL MYWORD.Width = 150

Language Statements IAF 8.0 DML

6-69

COCALL

#DIM1 = 200 COCALL MYWORD.Height = #DIM1

END_FORM

Example 6
FORM EXAMPLE_7 /ROW=1 /COL=1 /WIDTH=8 /HEIGHT=25

! Execute a COCALL statement to GET a property. ! Start word application. COCREATE "Word.Application" AS MYWORD

! GET property. #DIM1 = COCALL MYWORD.Width print #DIM1 #DIM2 = COCALL MYWORD.Height print #DIM2

END_FORM

Example 7
FORM EXAMPLE_8 /ROW=1 /COL=1 /WIDTH=8 /HEIGHT=25

! Execute a COCALL statement using named arguments. ! This example invokes a library (.EXE) with a method called ! User_info() which has three NAMED arguments, one OPTIONAL ! argument and one POSITIONAL argument. COCREATE "MyLib.EXE" AS MYLIB

#ID = 1258 ! Invoke function, for e.g., User_info(Username, UserID, Password, ! Optional IPCName, GroupID) ! First invoke with arguments in the specified order. COCALL MYLIB.User_info(Username="Jack", UserID="5049", & Password="IAF", IPCName = "ESCPC008", #ID)

6-70

Language Statements IAF 8.0 DML

COCALL

! Next invoke with NAMED arguments NOT in the specified order. COCALL MYLIB.User_info(Password="IAF", UserID="5049", & Username="Jack", IPCName = "ESCPC008", #ID)

! Next invoke without the OPTIONAL argument. COCALL MYLIB.User_info(Password="IAF, Username="Jack" ", & UserID="5049", , #ID)

END_FORM

Example 8
FORM EXAMPLE_9 /ROW=1 /COL=1 /WIDTH=8 /HEIGHT=25

! The following example shows how to start a word application and make ! it visible. It sets the width to 150 and height to 200. COCREATE "Word.Application" AS MYWORD

! Using the SET property, invoke the method "Width" and set the value. COCALL MYWORD.Width = 150

! Use variable #DIM1 to set the value of Height. #DIM1 = 200 COCALL MYWORD.Height = #DIM1

! Make Word Application visible. COCALL MYWORD.Visible = -1

END_FORM

Language Statements IAF 8.0 DML

6-71

COCALL

Example 9
FORM EXAMPLE_10 /ROW=1 /COL=1 /WIDTH=8 /HEIGHT=25

! Execute COCALL within a COCALL. ! The following example shows how to open a word application, resize ! the windows and use COCALL within a COCALL. It loops over ten times ! and moves/resizes the windows. It then adds a caption/title to the ! window. #WORD_APP = "Word.Application" COCREATE #WORD_APP as MYWORD COCALL MYWORD.Move(100, 50) COCALL MYWORD.Width = 150 #DIM1 = 200 COCALL MYWORD.Height = #DIM1

! Make Word Application visible. COCALL MYWORD.Visible = -1

! Initialize count to 0. #COUNT = 0

! Loop over "count" times and resize word application. WHILE (#COUNT < 10) COCALL MYWORD.ReSize( COCALL MYWORD.Width+15, & COCALL MYWORD.Height+10) #DIM2 = COCALL MYWORD.Left + 10 #DIM3 = COCALL MYWORD.Top + 5 COCALL MYWORD.Move(#DIM2, #DIM2)

! Decrement the counter. #COUNT = #COUNT + 1 END_WHILE

6-72

Language Statements IAF 8.0 DML

COCALL

! Add a title. COCALL MYWORD.Caption = "SuperEditor!!!"

END_FORM

Example 10
FORM EXAMPLE_11 /ROW=1 /COL=1 /WIDTH=8 /HEIGHT=25

! Execute multiple COCREATEs to verify functionality with multiple ! objects. This example opens word and excel applications. COCREATE "Word.Application" AS MYWORD1 COCREATE "Excel.Application" AS MYEXCEL1 COCREATE "Word.Application" AS MYWORD2 COCREATE "Excel.Application" AS MYEXCEL2

! Make excel applications visible COCALL MYEXCEL1.Visible = -1 COCALL MYEXCEL2.Visible = -1

! Make word applications visible COCALL MYWORD1.Visible = -1 COCALL MYWORD2.Visible = -1

END_FORM

Language Statements IAF 8.0 DML

6-73

COCREATE

COCREATE
Syntax
COCREATE co_name AS object_handle [/LOCATION=server_location] & [/PREF=server_type1[,server_type2[,server_type3]]] [/CLIENT]

or
COCREATE #variable_name AS #variable_obj [/LOCATION=#variable_loc] &[/PREF=server_type1[,server_type2[,server_type3]]] [/CLIENT]

Category
Utility

Description
COCREATE is used to create an instance of the COM/Active X object. co_name The co_name is a string constant whose value stores the identification of a COM object. The following table lists and describes the possible co_name variations particular to COM/ActiveX.

COM/ActiveX Component Name GUID or UUID

Description The Globally Unique Identifier or Universally Unique Identifier is comprised of a series of hexadecimal numbers enclosed in braces. This ID ensures that the COM object or interface is unique across all systems and platforms. The format of the UID is as follows: {XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXXXXXX}

6-74

Language Statements IAF 8.0 DML

COCREATE

COM/ActiveX Component Name Programmatic or Friendly Name

Description Programmatic Names or Friendly Names are "User Friendly" descriptive names of COM objects. The names are comprised of any series of ASCII characters enclosed in double quotes. For example their common usage format is as follows: "Word.Document.8" NOTE: Names are not guaranteed to be unique.

object_handle The object_handle is a unique handle name used as a reference to the instantiated COM object. COM object handles reside in their own name space and thus do not interact with the normal IAF variables. The scope of the object_handle behaves similarly to normal IAF variables. The life time of the handle exists from the creation of the object to the exit of the DML code. NOTE: Gem variable stored object handles are not released upon scope exiting. /LOCATION Qualifier The LOCATION qualifier is used to explicitly specify the location at which the COM object server should be loaded. The server_location may either be a string constant or Gem variable name of the remote machine, as in \\server, or the DNS (Domain Name System) name, such as server.com, www.rossinc.com , or 199.34.57.30. When the /LOCATION qualifier syntax is left out and /PREF=REMOTE, the server location defaults to the remote location specified in the Registry for the given COM object. /PREF Qualifier The COM object should be loaded as the specified server type. The /PREF qualifier is used to indicate the preferred order of server_type choices. The following table lists and describes the server_type options.

Server Type INPROC

Description COM objects are loaded into the client's process space (DLL)

Language Statements IAF 8.0 DML

6-75

COCREATE

Server Type SURROGATE LOCAL REMOTE

Description COM objects are loaded into a separate helper process that resides either locally or remotely COM objects run in a separate process on the same machine (EXE) COM objects run on a separate machine connected via a network (EXE)

The user can specify a list of one to four server_types: /PREF=REMOTE /PREF=LOCAL, INPROC /PREF= INPROC, LOCAL, REMOTE The qualifier /PREF=REMOTE,INPROC,LOCAL indicates that the COM object should first be loaded as a remote server. If that is not possible, an attempt should to be made to load it as an in-process server. If that fails, then it should be loaded as a local server. The /PREF qualifier is supplanted by the inclusion of the LOCATION qualifier. When the /PREF qualifier syntax is left out, the server type defaults to whatever the Registry deems appropriate. /CLIENT Qualifier The /CLIENT qualifier is introduced in IAF 6.1.5 and specifies that the COM object being accessed executes on the client. This is intended for use in DML programs running on any thin server platform (not just Windows), and will allow that DML to execute COM objects on the client. In the absence of the /CLIENT qualifier in DML running on a thin server, CallCOM will attempt to execute the COM object on the thin server platform - in this case, the platform must be Windows, or the following message will be issued:
"Functionality not implemented for COCREATE on this platform"

If this qualifier is used in an environment in which there is no thin client, or the thin client cannot be directly accessed (for example: character cell IAF on VMS or UNIX; DML Stored Procedures), an error message is issued:

6-76

Language Statements IAF 8.0 DML

COCREATE

"Functionality not implemented for COCREATE on this platform"

This qualifier is not necessary in DML running in GCWPro - if it is used no error message is generated and the COM object is executed on the GCWPro machine. #variable_name This is the name of the variable that indicates the identification of a COM object. For example: #MYWORD = "Word.Document" COCREATE #MYWORD AS WORD_DOC #variable_obj This is the name of the variable that indicates a reference to the instantiated COM object. For example: COCREATE "Word.Application" AS #MYWORD #variable_loc This is the name of the variable that provides the server location information as a string constant. It specifies the location at which the COM object server should be loaded.

Example 1
FORM EXAMPLE_1 /ROW=1 /COL=1 /WIDTH=8 /HEIGHT=25

! This dml statement shows how to create an instance of COM/ActiveX ! object, Word.Application, which is a "User Friendly" name. The object ! handle for this word application is stored in a unique handle name, ! myWord1. COCREATE "Word.Application" AS MYWORD1

Language Statements IAF 8.0 DML

6-77

COCREATE

! This dml statement uses the unique "UUID" for Word.Application, ! which is a series of hexadecimal numbers enclosed in braces. It ! is equivalent to the above DML statement. COCREATE {000209FF-0000-0000-C000-000000000046} AS MYWORD2

! This dml statement uses the unique "UUID" for Excel.Application. COCREATE {00020841-0000-0000-C000-000000000046} AS MYEXCEL

! This dml statement uses the unique "UUID" for Excel.Sheet. COCREATE {00020810-0000-0000-C000-000000000046} AS MYSHEET

! This dml statement uses the unique "UUID" for MAPI.Session, ! MAPI.Message and MAPI.Folder. These are the components of Microsoft ! Outlook e-mail Messaging system. COCREATE {3FA7DEB3-6438-101B-ACC1-00AA00423326} AS MYSESSION COCREATE {3FA7DEB4-6438-101B-ACC1-00AA00423326} AS MYMESSAGE COCREATE {3FA7DEB5-6438-101B-ACC1-00AA00423326} AS MYFOLDER

! This dml statement makes use of a GEM variable for storing the ! instance of Word.Application. #WORD_APP = "Word.Application" COCREATE #WORD_APP AS MYWORD3

! This dml statement makes use of a GEM variable for storing the ! instance of Word.Application AND also for the object handler. #WORD_APP = "Word.Application" COCREATE #WORD_APP AS #MYWORD4

! This dml statement is using the qualifier PREF set to INPROC. This ! specifies that the COM object should be loaded into the client's ! process space (DLL). COCREATE "Word.Application" AS MYWORD5 /PREF=INPROC

6-78

Language Statements IAF 8.0 DML

COCREATE

! This dml statement shows the usage of both the PREF and LOCATION ! qualifiers. The LOCATION in this case is a remote machine "ESCPC008". ! The PREF qualifier here indicates that the COM object should first be ! loaded as an in-process server. If that is not possible, an attempt ! should be made to load it as a remote server. If that fails, then try ! loading it as a local server. COCREATE "Word.Application" AS MYWORD6 /LOCATION="ESCPC008" & /PREF=INPROC,REMOTE,LOCAL

! This dml statement is using the /CLIENT qualifier. This ! allows the dml running on any thin server to execute ! COM objects on the client side. COCREATE "Word.Application" AS MYWORD5 /CLIENT

END_FORM

Language Statements IAF 8.0 DML

6-79

COM Special Parameter Considerations

COM Special Parameter Considerations

COM Success
These are COM operations that come back with a %SUCCESS condition and contain no side effects. The processing of further DML statements continues.

COM Warning
These are COM operations that come back with a %NORMAL condition but contain some unwanted side effects. They get reported with a lower severity warning message. The processing of further DML statements continues.

COM Error
These are COM operations that come back with a %FAILURE condition. They are reported with a high severity error message. The processing of further DML statements is discontinued if the error is not rectified.

Advanced Usage Notes

The /CLIENT qualifier has been introduced in the 6.1.5 version of IAF. This qualifier is intended for use in a thin server/thin client configuration. For any thin server, this qualifier will allow the COM/ActiveX DML statements to access COM objects residing on the client. All of the examples shown above can be modified to include the /CLIENT qualifier at COCREATE time. The following are the caveats regarding the behavior of the COM/ActiveX DMLs for various thin server/thin client configurations.

Accessing Windows Server from a remote PC

Say a user is running thin client on his PC and accessing Windows Server, without /CLIENT, on a remote PC. In this situation, if a user runs COM objects that have interactive user interface dialogs, then these dialogs will be displayed on the server side (on the remote PC). In such a situation, the

6-80

Language Statements IAF 8.0 DML

COM Special Parameter Considerations

server has the dialog container displayed waiting for user input (for e.g. click on OK button) before the test continues. On the thin client side, the user finds his PC in a "Locked" situation and is unaware that he has to respond to the user i/f dialog on the server side. Avoid running objects with interactive user interface dialogs in this case.

Running Thin Client/Server on the same PC

In this situation, if a user runs INPROC COM objects, without /CLIENT, that have interactive user interface dialogs, then these dialogs will not show up because it is trying to access its parent window (the server). Since the server has been started in a non-window mode and INPROC COM objects in general do not have containers, the dialog boxes will not be displayed. In general, INPROC COM objects need a parent to display information.

Third Party COM Objects

Some Third Party COM Objects might not be executable on a server on which the user does not have LOGON/PASSWORD privileges.

Language Statements IAF 8.0 DML

6-81

COMMIT

COMMIT
Syntax
COMMIT

Category
Data access

Description
This statement makes permanent all database updates that have occurred since the start of the current implicit or explicit transaction if the form executing the COMMIT statement also started the transaction. Transactions can be explicit, implicit, or pseudo. An explicit transaction begins with a START_TRANSACTION statement. An implicit transaction generally begins and ends within the context of a form. A pseudo transaction is a transaction started within the context of another transaction (which can be implicit or explicit). However, a pseudo transaction is not a real transaction. Only one real transaction can be in progress at any given time. If the current transaction is a real transaction (implicit or explicit), the COMMIT statement ends the transaction and updates the database. If the current transaction is a pseudo transaction, the COMMIT statement that pairs with the START_TRANSACTION statement does not end the real transaction in which the pseudo transaction was started, and does not update the database. However, the COMMIT statement does end any record stream that the pseudo transaction started. Note that when exiting a form, the transaction level is always the same as it was upon entering the form, regardless of whether additional transactions were started or committed within the form. Executing the COMMIT statement within a form causes IAF to place the operations completion status in the %STATUS special variable.

6-82

Language Statements IAF 8.0 DML

COMMIT

Related Topics
The following references contain information pertaining to the COMMIT statement: This chapters discussions of the START_TRANSACTION and ROLLBACK statements. The discussion of the %STATUS special variable in this manuals SPECIAL VARIABLES AND VALUE SYMBOLS chapter. The discussion of transactions in the IAF Users Guide.

Language Statements IAF 8.0 DML

6-83

COMPILE

COMPILE
Syntax
COMPILE [/qualifiers] input_file_spec [output_file_spec]

Category
Utilities and program development

Description
This statement compiles a DML file into its executable form. If you execute a source file directly, IAF implicitly compiles it into a temporary executable file. However, you can reduce a DML programs start-up time by compiling it explicitly via the COMPILE statement, and then performing the compiled program. By default, the COMPILE statement has no effect on the %STATUS special variable because any errors resulting from the COMPILE statements execution are signaled. However, it is possible to trap signaled errors to the %STATUS special variable via the BEGIN_SIGNAL_TO_STATUS statement. For details, refer to this chapters description of the BEGIN_SIGNAL_TO_STATUS statement.
input_file_spec

This is the file specification for the DML source file that IAF is to compile. The file specification must be enclosed in quotes. Unless you specify otherwise, IAF assumes the specified file has a filetype of .dml.
output_file_spec

This is the file specification for the output file resulting from the compilation process. The file specification must be enclosed in quotes. Unless you specify otherwise, IAF places the compiled file in the end users default directory. By default, the compiled file has the same filename as the source file (i.e. the .dml file) and a filetype of .dmc.

6-84

Language Statements IAF 8.0 DML

COMPILE

Qualifiers
The following qualifiers are valid for use with the COMPILE statement:
/CHECK

This qualifier causes IAF to perform the following checks during the compilation process: Check that all tables and fields exist in the database. Check that any system/facility names used by the MENU statement or any built-in facility function are valid. For details regarding builtin facility functions, refer to this manuals BUILT-IN FUNCTIONS chapter. Check that the DML program refers to all defined variables, and issue a warning for any defined variable that the program does not reference. Check that all variables that the DML program references are defined, and issue a warning for any referenced variable that is not defined in the DML form. Check that any message and parameter names that the DML program references are valid. Check that the DML program references all defined arrays, and issue a warning for any defined array that the program does not reference. IAF checks only the array name and not the arrays individual elements. Check that all arrays that the DML program references are defined, and issue a warning for any referenced array that is not defined in the DML program. IAF checks only the array name and not the arrays individual elements.
/LIST

This qualifier indicates that IAF is to generate a numbered line listing of the specified DML source file, including a cross reference of form names and line numbers. If you also append the /CHECK qualifier to the COMPILE statement, the listing also includes information on any triggers that the specified file executes.

Language Statements IAF 8.0 DML

6-85

COMPILE

/LOG=log_file_name

This qualifier enables you to specify the name of the log file to which IAF is to print any errors that occur during the compilation process. By default, IAF prints errors to the screen. This qualifier is especially useful when compiling DML source files in a batch job. IAF can write any error(s) to the given log file before continuing on to the next file or command in the batch.

Example
COMPILE sales_order_entry

This example causes IAF to compile the sales_order_entry.dml file to produce the sales_order_entry.dmc file.

Related Topics
The following references contain information pertaining to the COMPILE statement: This chapters discussions of the BEGIN_SIGNAL_TO_STATUS, END_SIGNAL_TO_STATUS, PERFORM, CROSS_REFERENCE, SET PERFORM, SWITCH, SWITCH_BASE, and MENU language statements. The discussion of .dmc files in this manuals DML File Information appendix. The discussion of the %STATUS special variable in this manuals Special Variables And Value Symbols chapter.

6-86

Language Statements IAF 8.0 DML

CONNECT

CONNECT
Syntax
CONNECT handle

Category
Client/server environment

Description
This statement causes the broker to allocate to the Client an Application Server for the application specified via the OPEN_APPLICATION statement whose handle matches the handle that the CONNECT statement specifies. You can execute multiple OPEN_APPLICATION/CONNECT statement constructs specifying different application handles to provide multiple connections to the given application. You can specify the application's handle where normal operation requires you to do so to facilitate Stored Procedure execution on the given application. IAF considers the handle that the most recently executed CONNECT statement specifies to be the default connect handle for any DML statements that expect a handle specification but that do not explicitly include one. To release the Application Server, you must issue a DISCONNECT statement specifying the same application handle name that the CONNECT statement specified. For the OPEN_APPLICATION and CONNECT sequence to succeed, one or more Servers must currently be running and available. IAF provides a Server Start-up Resource program to facilitate starting Servers. The program prompts for the name of a Server Start-up Resource file to use. A Server Start-up Resource file is a text file that contains information pertaining to a particular Server Application. Specifically, the Server Start- up Resource file indicates the Server Application's name and required access security privileges, and the databases with which it is associated. For details on running the Server Start-up Resource program, refer to the IAF guide that applies to your operating system. For details on Server Startup Resource files, refer to the IAF User's Guide. Upon starting a Server via the Server Start-up Resource program, the Server attaches to the database(s) specified via the DATABASE resource
Language Statements IAF 8.0 DML 6-87

CONNECT

in the Server Start-up Resource file, and registers the application's name and security access requirements with the node's IAF Broker. The Broker can subsequently use this information to establish a connection between a Client and the Server. A Client can be connected to multiple Servers at a time, but a Server can be connected to only one Client at a time.

Parameters
handle

The CONNECT statement must specify a handle that matches the application handle specified by a previously executed OPEN_APPLICATION statement.

Examples
OPEN_APPLICATION "tcp,host,6065\un\pw::MANU" as M CONNECT M

This example connects the Client to the Server Application named MANU, and establishes M as the connect handle.

Related Topics
The following references contain information pertaining to the SEND_TABLE statement: This chapters discussions of the OPEN_APPLICATION, RECEIVE_DATA, RECEIVE_TABLE, SEND_DATA, SEND_MESSAGE, EXECUTE, END_EXECUTE, CONNECT, and DISCONNECT statements. The discussion of the %STATUS special variable in this manual's Special Variables and Value Symbols chapter. The discussion of the IAF Client/Server Environment in the IAF User's Guide and the IAF guide that applies to your operating system.

6-88

Language Statements IAF 8.0 DML

CONTINUE

CONTINUE
Syntax
CONTINUE [keyword]

Category
Program flow

Description
This statement transfers program control to the end of the inner-most loop in which the statement occurs, thereby continuing the loop. WHILE/END_WHILE constructs and forms with header statements including the /REPEAT qualifier are loop constructs.

Keywords
The following table lists and describes the keywords that are valid for use with the CONTINUE statement. Keyword COMMIT Description This keyword causes IAF to commit the transaction that it implicitly begins prior to each iteration of a form whose header statement includes the /REPEAT qualifier. This keyword causes IAF to abandon the loop by passing control to the first statement following the applicable END_WHILE statement, and is valid only for loops that a WHILE statement creates. The CONTINUE OUT statement is equivalent to an explicit EXIT statement in a form that includes the /REPEAT qualifier. This keyword causes IAF to roll back the transaction that it implicitly begins prior to each iteration of a form whose header statement includes the /REPEAT qualifier.

OUT

ROLLBACK

Language Statements IAF 8.0 DML

6-89

CONTINUE

Example
WHILE (#COUNT<=100) FETCH CUSTOMERS/FAILURE=(CONTINUE OUT) IF (CUSTOMERS(INACTIVE_FLAG)=Y) #NO_INACTIVE=#NO_INACTIVE + 1 CONTINUE END_IF . . ! process customer record . #COUNT=#COUNT + 1 END_WHILE

Related Topics
The following references contain information that pertains to the CONTINUE statement: This chapters discussions of the WHILE and END_WHILE statements. The discussion of the /REPEAT form qualifier in this manuals FORMS AND FORM QUALIFIERS chapter and in the IAF Users Guide.

6-90

Language Statements IAF 8.0 DML

COPY_FILE

COPY_FILE
Syntax
COPY_FILE [/qualifiers] source_file destination_file

Description
Copies a source file to a destination file. Files can be copied from CLIENT to CLIENT, CLIENT to SERVER, SERVER to CLIENT, or SERVER to SERVER. By default, the file is copied as a text file. Add the /BINARY qualifier to cause the file to be copied as a binary file. On the OpenVMS platform, binary files are treated as organization sequential, recordtype fixed; recordsize 512 with record attributes none. Text files are treated as organization sequential, recordtype variable with carriage return carriage control. Copying a binary file from a non-OpenVMS platform an OpenVMS platform or vice versa results in the filesize becoming a multiple of 512 bytes. The IAF report directory (see GEM_REPORT_DIR SCV) used as the default directory on the client-side only (i.e., default source and/or destination directory when none is specified). When copying from SERVER to SERVER on the OpenVMS platform, the /BINARY and /TEXT qualifiers are ignored and need not be specified. (The file is copied using the callable convert API.) When copying a file from CLIENT to SERVER or SERVER to CLIENT, no actual file copy operation takes place if the DML program is not running in thin client/server mode.

Parameters
Source_file

A literal, a variable, or an expression containing the source file specification. A literal file specification must be quoted.
Destination_file

A literal, a variable, or an expression containing the destination file specification. A literal file specification must be quoted.

Language Statements IAF 8.0 DML

6-91

COPY_FILE

Qualifiers
/BINARY

Perform a binary file copy

/TEXT

Perform a text file copy

/FROM=keyword

Which side the file is to be copied from

/TO=keyword

Which side the file is to be copied to Both colon ':' and equal-sign '=' are acceptable qualifier value separators (i.e. /TO:CLIENT and /TO=CLIENT are both accepted). If no /FROM qualifier is specified, the default is SERVER. If no /TO qualifier is specified, the default is SERVER. Keyword is one of: 1. 2. 3. CLIENT SERVER A literal "CLIENT" or "SERVER", a variable containing CLIENT or SERVER or an expression evaluating to CLIENT or SERVER.

Example
COPY_FILE /TO=CLIENT "dan$:report.lis" "d:\reports\report.lis" COPY_FILE /FROM=CLIENT "d:\reports\report.lis" "dan$:report.lis;0" COPY_FILE /TO=CLIENT /BINARY "dan$:icon.bmp" "d:\pictures\icon.bmp" COPY_FILE /TO=(#A&#B) table1(field1) (table2(field2)&#C)

6-92

Language Statements IAF 8.0 DML

CORELEASE

CORELEASE
Syntax
CORELEASE obj_handle

or
CORELEASE #variable_obj

Category
Utility

Description
CORELEASE unloads and removes any references to a particular COM object. The object handle becomes indeterminate. COM object handles can be unloaded explicitly and implicitly. Using the CORELEASE statement is an example of an explicit unload. CORELEASE statement syntax is as follows: obj_handle This is the reference for the object instantiated in a previous COCREATE. #variable_obj This is the name of the variable that indicates a reference to the instantiated COM object in a previous COCREATE. The COM object handles can be implicitly unloaded when their global scope is exited. The scope is explained under object_handle in the COCREATE section.

Example 1
FORM EXAMPLE_12 /ROW=1 /COL=1 /WIDTH=8 /HEIGHT=25

! Execute a CORELEASE statement with object handler as a handle. ! This example creates an instance of excel application and then

Language Statements IAF 8.0 DML

6-93

CORELEASE

! unloads the object handler.

COCREATE "Excel.Application" AS MYEXCEL CORELEASE MYEXCEL

! Execute a CORELEASE statement with object handler as a variable. COCREATE "Excel.Application" AS #MYEXCEL CORELEASE #MYEXCEL

END_FORM

Example 2
FORM EXAMPLE_13 /ROW=1 /COL=1 /WIDTH=8 /HEIGHT=25

! The following example opens a word document. Several COCALLs are ! used to access the various methods as a collection of objects. The ! different attributes of font are invoked and text is entered in the ! word document. Before exiting, all the object handlers are released.

! Get the object handler for word application #WORD_APP = "Word.Application" COCREATE #WORD_APP AS MYWORD

! Make the application visible COCALL MYWORD.Visible = -1

! GET the handler for word document #DOC = COCALL MYWORD.Documents

! Open a word document COCALL #DOC.Add

6-94

Language Statements IAF 8.0 DML

CORELEASE

! GET the handler for word selection #SEL = COCALL MYWORD.Selection

! GET the handler to the selection of fonts #FONT = COCALL #SEL.Font

! SET the font size to 20 COCALL #FONT.Size = 20

! SET the font color to Yellow COCALL #FONT.ColorIndex = 2

! SET the font style to Bold COCALL #FONT.Bold = -1

! SET font animation to SparkleText COCALL #FONT.Animation = 3

! Now add the text to this word document with the above font attributes #TEXT = "Hello WORD, enter the WORLD of IAF through COM/ActiveX!!" COCALL #SEL.Text = #TEXT

! Quit the word document COCALL MYWORD.Quit

! Release all the objects. NOTE: The objects can be released in any order. CORELEASE #FONT CORELEASE #SEL CORELEASE #DOC CORELEASE MYWORD

END_FORM

Example 3

Language Statements IAF 8.0 DML

6-95

CORELEASE

FORM EXAMPLE_14 /ROW=1 /COL=1 /WIDTH=8 /HEIGHT=25

! The following is an example of an excel application. An excel ! workbook and a worksheet is opened. The worksheet is given a ! a name and is made visible. In this worksheet we add a movies table ! consisting of records for movie id, movie title and movie type. The ! workbook is then saved as excel.xls. At the end, all the object ! handlers are unloaded.

! Get the object handler for excel application COCREATE "Excel.Application" AS MYEXCEL

! Start excel application and give it a title COCALL MYEXCEL.Visible = -1 COCALL MYEXCEL.caption = "EXCEL with COM/ActiveX"

! GET the handler for the workbook and open it #WB = COCALL MYEXCEL.Workbooks COCALL #WB.Add

! GET the handler for worksheet(1), make it visible and give it a name #WSH = COCALL MYEXCEL.Worksheets(1) COCALL #WSH.Visible = -1 COCALL #WSH.Name = "Videos_Rentals"

! GET the handler for cell A1 and add a title to it #RANGE = COCALL MYEXCEL.Range("A1") COCALL #RANGE.Value = "Movie Id"

! GET the font handler for cell A1 and make it bold #FONT = COCALL #RANGE.Font COCALL #FONT.Bold = -1

! Unload the handlers for the cell and the font, since it's not

6-96

Language Statements IAF 8.0 DML

CORELEASE

needed anymore CORELEASE #FONT CORELEASE #RANGE

! GET the handler for cell B1 and add a title to it #RANGE = COCALL MYEXCEL.Range("B1") COCALL #RANGE.Value = "Movie Title"

! GET the font handler for cell B1 and make it bold #FONT = COCALL #RANGE.Font COCALL #FONT.Bold = -1

! GET the handler for cells in the range B1 to B10 and increase its width to 38 #WRANGE = COCALL MYEXCEL.Range("B1:B10") COCALL #WRANGE.ColumnWidth = 38

! Unload the handlers for the cells and the font, since it's not needed anymore CORELEASE #FONT CORELEASE #RANGE CORELEASE #WRANGE

! GET the handler for cell C1 and add a title to it #RANGE = COCALL MYEXCEL.Range("C1") COCALL #RANGE.Value = "Movie Type"

! GET the font handler for cell C1 and make it bold #FONT = COCALL #RANGE.Font COCALL #font.Bold = -1

! GET the handler for cells in the range C1 to C10 and increase its width to 15 #WRANGE = COCALL MYEXCEL.Range("C1:C10") COCALL #WRANGE.ColumnWidth = 15

! Unload the handlers for the cells and the font, since it's not needed anymore

Language Statements IAF 8.0 DML

6-97

CORELEASE

CORELEASE #FONT CORELEASE #RANGE CORELEASE #WRANGE

! Fill in the movie id information in the first column, cells A2 to A5 ! GET the handler for cell A2 and add movie id #RANGE = COCALL MYEXCEL.Range("A2") COCALL #RANGE.Value = "ADV601"

! Unload the handler CORELEASE #RANGE

! Do the same for A3 to A5 #RANGE = COCALL MYEXCEL.Range("A3") COCALL #RANGE.Value = "HOR401" CORELEASE #RANGE #RANGE = COCALL MYEXCEL.Range("A4") COCALL #RANGE.Value = "JUV201" CORELEASE #RANGE #RANGE = COCALL MYEXCEL.Range("A5") COCALL #RANGE.Value = "ROM201" CORELEASE #RANGE

! Fill in the movie title information in the second column, cells B2 to ! B5. GET the handler for cell B2 and add movie title #RANGE = COCALL MYEXCEL.Range("B2") COCALL #RANGE.Value = "7 years in Tibet"

! Unload the handler CORELEASE #RANGE

! Do the same for B3 to B5 #RANGE = COCALL MYEXCEL.Range("B3") COCALL #RANGE.Value = "I know what you did last summer" CORELEASE #RANGE

6-98

Language Statements IAF 8.0 DML

CORELEASE

#RANGE = COCALL MYEXCEL.Range("B4") COCALL #RANGE.Value = "A Bug's Life" CORELEASE #RANGE #RANGE = COCALL MYEXCEL.Range("B5") COCALL #RANGE.Value = "Shakespeare in Love" CORELEASE #RANGE

! Fill in the movie type information in the third column, cells C2 to ! C5. GET the handler for cell C2 and add movie type #RANGE = COCALL MYEXCEL.Range("C2") COCALL #RANGE.Value = "A"

! Unload the handler CORELEASE #RANGE

! Do the same for C3 to C5 #RANGE = COCALL MYEXCEL.Range("C3") COCALL #RANGE.Value = "H" CORELEASE #RANGE #RANGE = COCALL MYEXCEL.Range("C4") COCALL #RANGE.Value = "J" CORELEASE #RANGE #RANGE = COCALL MYEXCEL.Range("C5") COCALL #RANGE.Value = "R" CORELEASE #RANGE

! Quit excel application COCALL MYEXCEL.Quit

! Unload all the handlers CORELEASE #WSH CORELEASE #WB CORELEASE MYEXCEL

END_FORM

Language Statements IAF 8.0 DML

6-99

CORELEASE

Example 4
FORM EXAMPLE_15 /ROW=1 /COL=1 /WIDTH=8 /HEIGHT=25

! The example above showed how to CREATE an excel file via COM/ActiveX. ! The example in this section demonstrates how to read the contents ! that already exist in an excel file via COM/ActiveX. ! Here we will open the above created excel file "excel.xls" and ! GET the movies data from the various cells and print them out. ! When we are done GETing all the information, we will quit ! excel and unload all the object handlers.

! Get the object handler for excel application COCREATE "Excel.Application" AS MYEXCEL

! Start excel application COCALL MYEXCEL.Visible = -1

! GET the handler for the workbook and open it #WB = COCALL MYEXCEL.Workbooks COCALL #WB.Add

! Now OPEN the EXISTING excel file, "EXCEL.XLS" #FILE = "D:\EXCEL.XLS" COCALL #WB.Open(#FILE)

! GET the handler for cell A1 and read the data #RANGE = COCALL MYEXCEL.Range("A1") #READ = COCALL #RANGE.Value

! Print the data "Movie Id" which was in cell A1 print #READ

! Unload the handler

6-100

Language Statements IAF 8.0 DML

CORELEASE

CORELEASE #RANGE

! GET the handler for cell B1 and read the data #RANGE = COCALL MYEXCEL.Range("B1") #READ = COCALL #RANGE.Value

! Print the data "Movie Title" which was in cell B1 print #READ

! Unload the handler CORELEASE #RANGE

! GET the handler for cell C1 and read the data #RANGE = COCALL MYEXCEL.Range("C1") #READ = COCALL #RANGE.Value

! Print the data "Movie Type" which was in cell C1 print #READ

! Unload the handler CORELEASE #RANGE

! GET the handler for cell A2 and read the data #RANGE = COCALL MYEXCEL.Range("A2") #READ = COCALL #RANGE.Value

! Print the data "ADV601" which was in cell A2 print #READ

! Unload the handler CORELEASE #RANGE

! GET the handler for cell B2 and read the data #RANGE = COCALL MYEXCEL.Range("B2") #READ = COCALL #RANGE.Value

Language Statements IAF 8.0 DML

6-101

CORELEASE

! Print the data "7 years in Tibet" which was in cell B2 print #READ

! Unload the handler CORELEASE #RANGE

! GET the handler for cell C2 and read the data #RANGE = COCALL MYEXCEL.Range("C2") #READ = COCALL #RANGE.Value

! Print the data "A" which was in cell C2 print #READ

! Unload the handler CORELEASE #RANGE

! Quit excel application COCALL MYEXCEL.Quit

! Unload all the handlers CORELEASE #WB CORELEASE MYEXCEL

END_FORM

Example 5
FORM EXAMPLE_16 /ROW=1 /COL=1 /WIDTH=8 /HEIGHT=25

! The example in this section demonstrates the e-mail capabilities i.e. ! sending e-mail message to a recipient

! Get the object handler for MAPI.Session COCREATE "MAPI.Session" AS SESSION

6-102

Language Statements IAF 8.0 DML

CORELEASE

!Let the user know we are starting the EMAIL DEMO PAUSE_BLOCK /ROW=9 /COL=20 & /PROMPT="Welcome to EMAIL DEMO via COM/ActiveX in IAF!! & Press Return..."

! Logon using the session object ! Specify a valid profile name if you want to avoid the logon dialog ! box. Use named argument for the profile name ! COCALL SESSION.Logon(profileName="Microsoft Outlook")

COCALL SESSION.Logon

! GET the handler for MAPI.Session.Outbox.Messages.Add #OUTBOX = COCALL SESSION.Outbox #MESSAGE = COCALL #OUTBOX.Messages #ADD = COCALL #MESSAGE.Add

! SET the properties of the message object #SUBJECT = "TESTING EMAIL THROUGH COM/ACTIVEX IN IAF" #TEXT = "ENTER THE WORLD OF COM/ACTIVEX IN IAF!!!"

#TEXT1 = "This DEMO shows the e-mail capabilities using COM/ActiveX & in IAF. You can quickly and easily add e-mail capabilities, & i.e. sending and receiving e-mail messages, and interacting & with folders and address books. You can create programmable & message objects, and then use their properties and methods & to meet the needs of your application."

#TEXT2 = "THANK YOU FOR WATCHING CallCOM/ACTIVEX DEMO!!!"

COCALL #ADD.subject = #SUBJECT COCALL #ADD.text = #TEXT & chr(13) & chr(10) & #TEXT1 & chr(13) & chr(10) & #TEXT2

Language Statements IAF 8.0 DML

6-103

CORELEASE

! Get the handler for a recipient object to the ADD.Recipients collection #RECIPIENT = COCALL #ADD.Recipients #RECPADD = COCALL #RECIPIENT.Add

! SET the properties of the recipient object COCALL #RECPADD.name = "Nadira_Javaid@Rossinc.com" COCALL #RECIPIENT.Resolve

! Now send the message ! Use named argument to avoid the dialog box COCALL #ADD.send(showDialog = "False")

! Logoff using the session object COCALL SESSION.Logoff

! Let the user know we are done with EMAIL DEMO PAUSE_BLOCK /ROW=9 /COL=20 & /PROMPT="Check your EMAIL!! Thank you for watching this demo!"

! Unload all the handlers CORELEASE #RECPADD CORELEASE #RECIPIENT CORELEASE #ADD CORELEASE #MESSAGE CORELEASE #OUTBOX CORELEASE SESSION

END_FORM

6-104

Language Statements IAF 8.0 DML

CPANEL

CPANEL
Introduction
CPANEL is used to add a task item to the Smart Client Container DMLDesktop TaskPad. When clicked, the task item sends a command to an SCC Application add-in.

Syntax
CPANEL statement to add a Taskpad item:
CPANEL /TEXT=text_string & [/ID=id_string] & [/GLOBAL] & [/PARAMETER=(NAME=name_string, VALUE=value_string)] & [/DESC=desc_string]& [/NAME=name_string ]& [/ADDIN=addin_string]& [/FACILITY=db.system:facility|/DML= dml_string|/URL=url_string| /WEB_APP=webapp_string]& [/DRILLIN=drillin_string]

CPANEL statement to remove a Taskpad item:

CPANEL [/TEXT=text_string | /ID=id_string] /REMOVE

Description
The first CPANEL statement above is used to add a task to the Taskpad. The task is added at the end (bottom) of the list of existing Taskpad items. If the item already exists in the Taskpad, it is replaced. When the Taskpad item is clicked by the user, the associated command (action item) is sent to the target add-in for processing. The second format is used to remove a task from the Taskpad.

Qualifiers
/TEXT=text_string

Language Statements IAF 8.0 DML

6-105

CPANEL

This is the text description for the task item. It is displayed in the Taskpad. If this needs to be localized it is the responsibility of the DML code to pass the localized value. This is not localized by the DMLDesktop add-in or the Smart Client Container. The value specified is also used as the identifier for the task unless the /ID qualifier is also specified.
/ID=id_string

This optional qualifier specifies the identifier for the task, and identifies the task in the Taskpad. If omitted, the value specified by the /TEXT qualifier is used as the identifier. This qualifier is useful in situations where tasks are being replaced with tasks displaying different text.
/GLOBAL

This optional qualifier specifies that the Taskpad item is global. With this qualifier, the Taskpad item will remain in the Taskpad until removed by another CPANEL statement with a /REMOVE qualifier. If this qualifier is not specified, the Taskpad item will be automatically removed from the Taskpad when the form containing the CPANEL statement is removed. Note that Taskpad items added by PROCEDURE_FORMs will remain when the PROCEDURE_FORM ends. The Taskpad items will be automatically removed when the parent form is removed, unless the /GLOBAL qualifier is used. Taskpad items added by CPANEL statements in TITLE FORMs will remain in the Taskpad until the facility exits, or until removed by a CPANEL statement with a /REMOVE qualifier.
/PARAMETER= (NAME=name_string, VALUE=value_string)

This qualifier allows named parameters (or attributes) and their values to be specified. Multiple /PARAMETER qualifiers can be used.
/DESC=desc_string

Optionally specifies a description for the Taskpad item. This string is displayed as a tooltip when the mouse hovers over the item in the Taskpad. If not specified then no tooltip is displayed.
/NAME=name_string

This specifies the name of the command associated with this Taskpad item. This name should be the name of a valid command implemented by the target add-in. This is the command that the target add-in is expected to execute when the Taskpad item is clicked. This is shorthand for:
6-106 Language Statements IAF 8.0 DML

CPANEL

/PARAMETER= (NAME="NAME", VALUE=name_string)

/ADDIN=addin_string

This specifies the name of the SCC add-in to receive the command. If not specified it defaults to "DMLDesktop". This is shorthand syntax for the following:
/PARAMETER= (NAME="APPLICATION", VALUE=addin_string)

/FACILITY=db.system:facility

This specifies the facility to be run for this Taskpad item. This is equivalent to specifying:
/PARAMETER= (NAME="TagName", VALUE="GemFacility") & /PARAMETER= (NAME="DATABASE", VALUE=db) & /PARAMETER= (NAME="SYSTEM", VALUE=system) & /PARAMETER= (NAME="FACILITY", VALUE=facility)

/DML=dml_string

This is the DML form to be performed. Shorthand for:

/PARAMETER= (NAME="TagName", VALUE="GemPerform") & /PARAMETER= (NAME="DML", VALUE=dml_string)

/WEB_APP=webapp_string

This is the web app to be started. Shorthand for:

/PARAMETER= (NAME="TagName", VALUE="WebApplication") & /PARAMETER= (NAME="url", VALUE=webapp_string)

/URL=url_string

This is used to display a web page. Shorthand for:

/PARAMETER= (NAME="TagName", VALUE="URL") & /PARAMETER= (NAME="url", VALUE=url_string)

/DRILLIN=drillin_string

This is the startup parameter for the facility drill-in. This is equivalent to specifying:
/PARAMETER= (NAME="StartUpParams", VALUE=drillin_string)

/REMOVE

Language Statements IAF 8.0 DML

6-107

CPANEL

When specified, the Taskpad item identified by /TEXT or /ID is removed from the Taskpad.

Examples
See Appendix K "CPANEL Usage Guide" for examples.

6-108

Language Statements IAF 8.0 DML

CROSS_REFERENCE

CROSS_REFERENCE
Syntax
CROSS_REFERENCE

Category
Utilities and program development

Description
This statement invokes IAFs Cross-References utility, which enables you to produce a report listing the table(s) and field(s) that the compiled DML source files (i.e. .dmc files) in a given directory reference. IAF writes the report to the current default directory with a default filename and filetype of gem_xref_report.lis. The report indicates the name and location of the .dmc files, the table and field names that each .dmc file references, and whether the referenced data is read-only, write-only, or read- write. Upon invoking the Cross-References utility, IAF displays the Print CrossReference for Tables and Fields window to enable you to specify the table(s), field(s), and directory on which to base the report, and whether or not the report is to run in a batch queue. IAF automatically runs the report on all .dmc files in the specified directory. Therefore, if you do not specify the table(s) on which to base the report, IAF runs the report for all tables that the .dmc files in the given directory reference. Likewise, if you do not specify the field(s) on which to base the report, IAF runs the report for all fields that the .dmc files in the given directory reference in the given table(s). If you do not specify the directory on which to base the report, IAF runs the report for all .dmc files in the current default directory. In response to the prompts in the window, you can specify that the report is to contain references for a single table or range of tables, a single field or range of fields, and/or a directory other than the current default directory.

Language Statements IAF 8.0 DML

6-109

CROSS_REFERENCE

Related Topics
The following reference contains information pertaining to the CROSS_REFERENCE language statement: This chapters discussion of the COMPILE statement.

6-110

Language Statements IAF 8.0 DML

DCL

DCL
Syntax
DCL [/qualifiers] command_expression

Category
Miscellaneous

Description
This statement is synonymous with the DML CLI (Command Language Interpreter) statement and is provided only for compatibility with previous IAF versions. The CLI statement is the preferred statement and should be used instead of the DCL statement. For details regarding the CLI statement, refer to its description in this chapter. Executing the DML statement within a form causes IAF to place the operations completion status in the %STATUS special variable.

Related Topics
The following references contain information pertaining to the DCL statement: This chapters discussions of the CLI and $ (dollar sign) language statements. The discussion of the %STATUS special variable in this manuals Special Variables And Value Symbols chapter.

Language Statements IAF 8.0 DML

6-111

DELETE ADMIN_IDS

DELETE ADMIN_IDS
Syntax
DELETE ADMIN_IDS "role_name:admin_ids"

Category
Program flow

Description
This command deletes the requested admin(s) from the current database for the specified role. role_name This is a string that represents a valid role name for which the requested admins will be deleted from the current database. admin_ids This is the admin id(s) to be deleted from the current database for the specified role. The maximum number of admin ids to be deleted at one time is ten, with comma(,) as the separator. If an "*" is selected for the admin_id, all admin id(s) will be deleted from the current database for the specified role.

Examples
DELETE ADMIN_IDS "ADMIN:bob"

Deletes Bob from the ADMIN role.

DELETE ADMIN_IDS "ADMIN:bob,elmo,vladimir

Deletes Bob, Elmo, Vladimir from the ADMIN role.

DELETE ADMIN_IDS "ADMIN:*"

Deletes all admins from the ADMIN role.

6-112

Language Statements IAF 8.0 DML

DELETE FROM

DELETE FROM
Syntax
DELETE [/ARCHIVE] [ALL] FROM [database_handle.]table_name

or
DELETE [/ARCHIVE] [ALL] FROM #variable_name

Category
Data access

Description
The DELETE FROM statement without the ALL keyword causes IAF to delete the record that is currently in the user buffer associated with the specified table. IAF issues a warning if no record is currently in the user buffer when this statement executes. Various DML statements and constructs cause IAF to place records into user buffers associated with specified tables. These statements include, but are not limited to, the following: form header statements that include any record selection qualifiers (for example; /TABLE, /WITH, /SORT) INPUT_BLOCK statements that complete successful domain validations CHECK_DOMAIN statements FETCH statements FIND IN statements START_STREAM statements For details regarding user buffers, refer to the IAF Users Guide. For details regarding form header statements and record selection qualifiers, refer to this manuals FORMS AND FORM QUALIFIERS chapter For details regarding the INPUT_BLOCK statement, refer to this manuals BLOCKS AND BLOCK QUALIFIERS. For details regarding the CHECK_DOMAIN, FETCH, FIND_IN, and START_STREAM statements, refer to their descriptions in this chapter.

Language Statements IAF 8.0 DML

6-113

DELETE FROM

The DELETE FROM statement with the ALL keyword causes IAF to delete all records from the specified table. This is the most efficient way to clear a virtual table (i.e. it is more efficient than using DELETE FROM in a loop). For details regarding virtual tables, refer to the IAF Users Guide. Executing the DELETE FROM statement (with or without the ALL keyword) within a form causes IAF to place the operations completion status in the %STATUS special variable.
database_handle

This is the handle for the database in which the table whose record(s) IAF is to delete resides. It is necessary to include a database handle only if you have invoked multiple databases, and the specified table does not exist in the current default database.
table_name

In the first syntax on the preceding page, this is the name of the table whose record(s) IAF is to delete.
#variable_name

In the second syntax on the preceding page, this is the name of a variable that contains the name of the table whose record(s) IAF is to delete. Optionally, a database handle may precede the table name (see the description of database_handle above for details).

Domain and Trigger Considerations

IAF takes certain actions when preparing to execute the DELETE FROM statement if the record that the statement is to delete is part of an implicit or explicit domain, or includes a field that has an update trigger defined for it. Specifically, these actions are as follows.
For a record that is part of a domain:

IAF issues an error message and does not execute the DELETE FROM statement if deleting the record violates an existing implicit or explicit domain that involves another table. For example, IAF issues an error message if you attempt to delete a sales order header record in the ORDERS table if any associated order lines records still exist in the ORDER_LINES table.

6-114

Language Statements IAF 8.0 DML

DELETE FROM

For a record that includes an update trigger field:

IAF automatically forces execution of any update trigger defined for the fields in the table. It does this prior to performing any deletion by setting to zero or blank any field that has a trigger defined for it. IAF provides read-only internal trigger variables that contain the different values of a trigger field (i.e. its value prior to the triggers execution, after the triggers execution, etc.). The #GM_NEW internal trigger variable contains the new value of the trigger field (in this case zero or blank). The #GM_OLD internal trigger variable contains the value of the trigger field prior to IAFs execution of the DELETE FROM statement.

Qualifier
The following qualifier is valid for use with the CONNECT statement:
/ARCHIVE

This qualifier causes IAF to pass the %ARCHIVE status to the #GM_MODE trigger variable. If the DELETE FROM statement does not include this qualifier, the #GM_MODE variable contains the value, %DELETE, after execution of the DELETE FROM statement. The %ARCHIVE status informs the trigger that the record has been deleted for archive purposes (i.e. it has been moved to another table prior to execution of the DELETE FROM statement). The trigger can then access the record in the archive table if desired.

Examples
DELETE ALL FROM CUSTOMERS DELETE FROM SALES_ORDER_LINES #NAME=SALES_ORDER_LINES DELETE /ARCHIVE FROM #NAME

Related Topics
The following references contain information pertaining to the DELETE FROM statement: This chapters discussions of the CHECK_DOMAIN, FETCH, FIND IN, and START_STREAM statements. The discussion of the %STATUS special variable in this manuals SPECIAL VARIABLES AND VALUE SYMBOLS chapter. The discussions of record streams, buffers, update triggers, domains, and virtual tables in the IAF Users Guide.

Language Statements IAF 8.0 DML

6-115

DELETE ROLES

DELETE ROLES
Syntax
DELETE ROLES role-name

Category
Program flow

Description
This DML statement deletes the requested role(s) from the current database. role-name This is a string that represents the role(s) to be deleted from the database. The maximum number of roles to be deleted at one time is ten, with a comma (,) as the separator. If an asterisk (*) is selected for the role_name, all roles will be deleted from the current database.

Examples
DELETE ROLES "ADMIN"

Deletes the ADMIN role from the database.

DELETE ROLES ADMIN,SALES,DEV

Deletes ADMIN, SALES, and DEV roles from the database.

DELETE ROLES *

Deletes all roles from the database.

6-116

Language Statements IAF 8.0 DML

DELETE ROLE_USER

DELETE ROLE_USER
Syntax
DELETE ROLE_USERS "role_name:user_id"

Category
Program flow

Description
This command deletes the requested user(s) from the specified role in the current database. role_name This is the role for which the specified user(s) will be deleted. user_id This is a string that represents the user(s) to be deleted for the specified role in the current database. The maximum number of users to be deleted at one time is ten, with a comma (,) as the separator. If an asterisk (*) is selected for a user id, all users will be deleted for the specified role.

Example
DELETE ROLE_USERS "DEV:dinats"

Deletes user dinats from role DEV.

DELETE ROLE_USERS "DEV:dinats,lisa"

Deletes users dinats,lisa from role DEV.

DELETE ROLE_USERS "DEV:*"

Deletes all users from role DEV.

Language Statements IAF 8.0 DML

6-117

DELETE USER_ROLE

DELETE USER_ROLE
Syntax
DELETE USER_ROLES "user_id:role_name"

Category
Program flow

Description
This command deletes the requested role(s) from the specified user in the current database. user_id This is the user for which the specified role(s) will be deleted. role_name This is a string that represents the role(s) to be deleted for the specified user in the current database. The maximum number of roles to be deleted at one time is ten, with comma(,) as the separator. If "*" is selected for a role_name, all roles will be deleted for the specified user.

Examples
DELETE USER_ROLES "dinats:DEV"

Deletes role DEV from dinats.

DELETE USER_ROLES "dinats:DEV,USERS"

Deletes roles DEV, USERS from dinats.

DELETE USER_ROLES "dinats:*"

Deletes all roles from dinats.

6-118

Language Statements IAF 8.0 DML

DIR

DIR
Syntax
DIR file_specification

Category
Miscellaneous

Description
This statement displays a simple file directory in a table edit format. IAF displays the names of the files that match the given file specification. The file specification can include the * wildcard character to represent zero or more unknown characters, and can also include other operating system dependent wildcard characters. IAF also provides the CLI (Command Language Interpreter) statement to enable you to issue commands directly to the current operating system to perform more detailed directories when you require them. For details regarding the CLI statement, refer to its description in this chapter.
file_specification

This is a file specification indicating the file(s) that IAF is to include in the directory listing. As previously mentioned, it can include the * wildcard character to represent zero or more unknown characters, in addition to other operating system dependent wildcard characters.

Example
DIR *.dml

This example displays a table edit directory listing of all files having the filetype .dml in the current default directory.

Related Topics
The following references contain information pertaining to the DIR statement: This chapters discussion of the CLI statement. The discussion of the File Manager utility in the IAF System Reference Manual.

Language Statements IAF 8.0 DML

6-119

DISCONNECT

DISCONNECT
Syntax
DISCONNECT handle

Category
Client/Server environment

Description
This statement releases a previously allocated Application Server from service to the Client. Any database transactions started via Stored Procedures must be closed for the DISCONNECT statement to execute. IAF rolls back any outstanding transactions before executing the DISCONNECT statement.

Parameters
handle

The DISCONNECT statement must specify a handle that matches the application handle specified by a previously executed CONNECT statement, and indicates the Application Server connection to disconnect.

Examples
DISCONNECT M

This example terminates the client/server connection that the M connect handle represents.
DISCONNECT #LOOKUP

This example terminates the client/server connection that the connect handle in the #LOOKUP variable represents.

Related Topics
The following references contain information pertaining to the SEND_TABLE statement:

6-120

Language Statements IAF 8.0 DML

DISCONNECT

This chapters discussions of the RECEIVE_DATA, RECEIVE_TABLE, SEND_DATA, SEND_MESSAGE, EXECUTE, END_EXECUTE, CONNECT, and DISCONNECT statements. The discussion of the %STATUS special variable in this manuals Special Variables and Value Symbols chapter. The discussion of the IAF Client/Server Environment in the IAF User Guide and the IAF guide that applies to your operating system.

Language Statements IAF 8.0 DML

6-121

DISPLAY

DISPLAY
Syntax
DISPLAY keyword

Category
Screen input and output

Description
This statement causes IAF to redisplay the NORMAL or TABLE_EDIT form that executes the statement. The specified keyword indicates the specific display operation that IAF is to perform.

Keywords
The following table lists and describes the option keywords that are valid for use with the DISPLAY statement. Keyword CLEAN Description This keyword causes IAF to clear all input and output display areas in the given form. IAF fills the screen display areas with spaces.

6-122

Language Statements IAF 8.0 DML

DISPLAY

Keyword DEFAULTS

Description This keyword causes IAF to display the default data for all input and output blocks in the given form. IAF determines the default data to display by examining the data in the appropriate user buffer, and any /SOURCE or /TARGET qualifiers that the blocks include. This keyword facilitates displaying a records default data prior to its modification. For example, assume that the DISPLAY DEFAULTS statement is in a form that modifies the CUSTOMERS table records. The form prompts the end user to enter a customer ID. IAF validates the entered customer ID and places the applicable customer record into the user buffer, and then executes the DISPLAY DEFAULTS statement, causing the form to display the customer records details. IAF validates both implicit and explicit domains on any input block in the form, and any explicit domain on any output block in the form when it executes the DISPLAY DEFAULTS statement. To include the DISPLAY DEFAULTS statement in a form, place the statement within a BEGIN_BLOCK/END_BLOCK construct (see this sections example).

BEGIN_UPDA TE

This keyword causes IAF to perform all screen updates in a batch. Normally, IAF updates the screen when the end users response to a prompt causes the screen image to change. The DISPLAY BEGIN_UPDATE statement causes IAF to update the screen only upon executing a DISPLAY END_UPDATE statement or receiving a required keyboard input. This keyword causes IAF to stop performing screen updates in batch. When IAF executes the DISPLAY END_UPDATE statement, the screen window displays in its final stage (i.e. as it appeared after the last screen image update). The DISPLAY END_UPDATE statement has no effect if screen output batching is currently active, which is the default behavior. For details on setting screen output batching, refer to this chapters description of the SET SCREEN statement.

END_UPDATE

Language Statements IAF 8.0 DML

6-123

DISPLAY

Keyword FLUSH

Description This keyword causes IAF to immediately update the screen with any changes, and is useful in situations in which it would be prohibitive to wait for the screen to update at the forms next input. This keyword causes IAF to redisplay the current screen, and is useful when the screen display becomes corrupted.

REFRESH

Example
FORM MAIN /ROW=3 /COL=2 /HEIGHT=19 /WIDTH=78 & /TITLE=Modify Customer Details & /REPEAT BEGIN_BLOCK CUSTOMER INPUT_BLOCK /ROW=10 /COL=40 & /PROMPT=FIELD_PROMPT(CUSTOMER_ID) & /TARGET=CUSTOMER(ID) DISPLAY DEFAULTS ! ! This causes IAF to display the current customer ! records NAME and ADDRESS_1 fields. END_BLOCK INPUT_BLOCK /ROW=12 /COL=40 & /PROMPT=FIELD_PROMPT(NAME) & /TARGET=CUSTOMER(NAME) INPUT_BLOCK /ROW=13 /COL=40 & /PROMPT=FIELD_PROMPT(ADDRESS_1) & /TARGET=CUSTOMER(ADDRESS_1) END_FORM

Related Topics
The following references contain information pertaining to the DISPLAY statement: This chapters discussion of the SET SCREEN statement. The discussion of the input and output blocks and their qualifiers in this manuals BLOCKS AND BLOCK QUALIFIERS chapter. The discussion of domains in the IAF Users Guide.

6-124

Language Statements IAF 8.0 DML

DOCUMENTATION

DOCUMENTATION
Syntax
DOCUMENTATION

Category
Utilities and program development

Description
This statement invokes IAFs System Documentation utility, and displays the IAF System Documentation menu. This menu contains options that enable you to produce reports on the metadata that the current database contains. The Documentation utility produces reports on metadata pertaining to tables, fields, indices, domains, messages, parameters, triggers, field help, facilities, and systems. For details regarding the Documentation utility, refer to the IAF System Reference Manual.

Example
You can invoke the Documentation utility by entering either of the following commands at the IAF command line prompt (GEM> by default):
DOCUMENTATION DOC

Related Topics
The following reference contains information pertaining to the DOCUMENTATION statement: The discussion of the Documentation utility in the IAF System Reference Manual.

Language Statements IAF 8.0 DML

6-125

EDIT

EDIT
Syntax
EDIT filename

Category
Miscellaneous

Description
The EDIT statement invokes the text editor that the GEM_EDITOR System Customization Variable (SCV) specifies, and loads the specified file into the editor to enable you to edit it. If the GEM_EDITOR SCV is undefined, the operating system on which IAF is currently running governs the editor that IAF invokes.
filename

This is the name of the file that IAF is to load into the given text editor.

Examples
EDIT my_file.doc EDIT sales_order_inquiry.dml

Related Topics
The following reference contains information pertaining to the EDIT statement: The discussion of the GEM_EDITOR SCV in the IAF guide that applies to your operating system.

6-126

Language Statements IAF 8.0 DML

EDIT/DICTIONARY

EDIT/DICTIONARY
Syntax
EDIT/DICTIONARY

Category
Utilities and program development

Description
This statement invokes IAFs Data Definition Editor utility. The Data Definition Editor enables you to define and maintain the elements in the Data Dictionary. If you are not attached to a database prior to executing this statement, IAF displays a menu to enable you to create a new database or invoke an existing database. Otherwise, executing this statement causes IAF to display the Data Definition Editor menu. This menu contains options enabling you to define, view, modify, and/or delete the metadata in the current default database.

Related Topics
The following references contain information pertaining to the EDIT/DICTIONARY statement: This chapters discussion of the UTILITIES statement. The discussion of the Data Definition Editor in the IAF System Reference Manual and the IAF guide that applies to your database engine.

Language Statements IAF 8.0 DML

6-127

EDIT/FORMS

EDIT/FORMS
Syntax
EDIT/FORMS [file_spec]

Category
Utilities and program development

Description
This statement invokes IAFs Forms Editor utility. Executing the EDIT/FORMS statement with a DML source file specification (file_spec) causes IAF to immediately load the given file into the Forms Editor in edit mode. Executing the EDIT/FORMS statement without a DML source file specification causes IAF to display the Editor Options menu, which contains options enabling you to create, edit, save, recall, and/or perform forms. For details regarding the Forms Editor, refer to the IAF System Reference Manual. Attempting to execute the EDIT/FORMS statement without being attached to a database generates an error.
file_spec

This is the file specification for a DML source file (default filetype .dml) on which the Forms Editor is to operate.

Examples
EDIT/FORMS EDIT/FORMS sales_order_entry

Related Topics
The following references contain information pertaining to the EDIT/FORMS statement: This chapters discussion of the UTILITIES statement. The discussion of the Forms Editor in the IAF System Reference Manual.

6-128

Language Statements IAF 8.0 DML

EDIT/REPORTS

EDIT/REPORTS
Syntax
EDIT/REPORTS [file_spec]

Category
Utilities and program development

Description
This statement invokes IAFs Report Editor utility. Executing the EDIT/REPORT statement with a DML source file specification (file_spec) causes IAF to immediately load the given file into the Report Editor in edit mode. Executing the EDIT/REPORTS statement without a DML source file specification causes IAF to display the Editor Options menu, which contains options enabling you to create, edit, save, recall, and/or perform REPORT forms. For details regarding the Report Editor, refer to the IAF System Reference Manual. Attempting to execute the EDIT/REPORTS statement without being attached to a database generates an error.
file_spec

This is the file specification for a DML source file (default filetype .dml) on which the Report Editor is to operate.

Examples
EDIT/REPORTS EDIT/REPORTS members_listing

Related Topics
The following references contain information pertaining to the EDIT/REPORTS statement: This chapters discussion of the UTILITIES statement. The discussion of the Report Editor in the IAF System Reference Manual.

Language Statements IAF 8.0 DML

6-129

EDIT/SECURITY

EDIT/SECURITY
Syntax
EDIT/SECURITY

Category
Utilities and program development

Description
This statement invokes IAFs Security Editor utility, which enables you to define and maintain security within a IAF system. Upon invoking the Security Editor, IAF displays the Security Maintenance menu. This menu contains options enabling you to place security protection on the current database and its metadata, and to perform audit functions. Attempting to execute the EDIT/SECURITY statement without being attached to a database generates an error.

Related Topics
The following references contain information pertaining to the EDIT/SECURITY statement: This chapters discussion of the UTILITIES statement. The discussion of IAFs Auditing Facility in the IAF System Reference Manual. The discussion of the Security Editor in the IAF guide that applies to your database engine.

6-130

Language Statements IAF 8.0 DML

EDIT/SYSTEM

EDIT/SYSTEM
Syntax
EDIT/SYSTEM

Category
Utilities and program development

Description
This statement invokes IAFs System Definition Editor utility, which enables you to create and maintain the components of a IAF system. Upon invoking the System Definition Editor, IAF displays the System Definition menu. This menu contains options enabling you to define and maintain the hierarchical structure of facilities that comprise a system. A facility represents the common functionality of a subset of a system. For details regarding the System Definition Editor, refer to the IAF System Reference Manual. Attempting to execute the EDIT/SYSTEM statement without being attached to a database generates an error.

Related Topics
The following references contain information pertaining to the EDIT/SYSTEM statement: This chapters discussion of the UTILITIES statement. The discussion of the System Definition Editor in the IAF System Reference Manual.

Language Statements IAF 8.0 DML

6-131

EDIT/TABLE

EDIT/TABLE
Syntax
EDIT/TABLE [/FIND][database_handle.][table_name[(field_name1[,field_name2[ ,...]])]]

Category
Utilities and program development

Description
This statement invokes IAFs Table Editor utility, which enables you to add, modify, and delete records in a table edit format. Upon invoking the Table Editor, IAF displays the Simple Table Editing window. This window enables you to specify the name of the table on which the Table Editor is to operate. You can then specify which of the tables non-PID fields the Table Editor is to display in the table edit window. IAF automatically includes the tables PID fields in the window. You can optionally include a table name with the EDIT/TABLE statement. If you do, IAF bypasses the Simple Table Editing window and displays as many of tables fields as it can fit across the table edit window in 132 column mode screen. Attempting to execute the EDIT/TABLE statement without being attached to a database generates an error.
database_handle

This is the handle for the database that holds the table upon which the Table Editor is to operate. It is necessary to include a database handle only if you have invoked multiple databases, and the specified table does not exist in the current default database.

6-132

Language Statements IAF 8.0 DML

EDIT/TABLE

table_name[(field_name1[,field_name2[,...]])]

This is the name of the table, and optionally, one or more fields, on which the Table Editor utility is to operate. If you do not specify a table name, IAF displays the Simple Table Editing window, which prompts you to enter a table name. If you specify a table name and no field names, IAF bypasses the Simple Table Editing window and displays as many of the tables fields as it can fit across the table edit window in 132 column screen mode. If you specify a table name and one or more field names, IAF bypasses the Simple Table Editing window and displays the specified fields in the table edit window, fitting as many as it can across the window, and switching to 132 column screen mode if necessary.

Qualifier
The following qualifier is valid for use with the EDIT/TABLE statement:
/FIND

This qualifier causes IAF to display a data filter window prior to selecting the record set from the specified table. The data filter window enables you to enter search criteria for the records that are to appear in the table edit window. Only those records for which the given search criteria is true appear in the table edit window.

Examples
EDIT/TABLE /FIND STOCK_MOVEMENTS EDIT/TABLE MEMBERS(MEMBERSHIP_TYPE)

Data Auditing
Use the GEM_TED_DATA_AUDIT SCV to enable TED data auditing on all table fields by default.

Example
GEM_TED_DATA_AUDIT=TRUE

Related Topics
The following references contain information pertaining to the EDIT/TABLE statement: This chapters discussion of the UTILITIES statement. The discussion of the Table Editor in the IAF System Reference Manual.
Language Statements IAF 8.0 DML 6-133

END_DISABLE_TRIGGER

END_DISABLE_TRIGGER
Syntax
END_DISABLE_TRIGGER

Category
Program flow

Description
This statement re-enables update triggers that were previously disabled as a result of executing the BEGIN_DISABLE_TRIGGER statement.

Example
BEGIN_DISABLE_TRIGGER MEMBERS(MEMBER_ID)=#TEST_ID END_DISABLE_TRIGGER

Related Topics
The following references contain information pertaining to the END_DISABLE_TRIGGER statement. This chapters discussion of the BEGIN_DISABLE_TRIGGER statement. The discussion of update triggers in the IAF System Reference Manual section pertaining to the Data Definition Editor.

6-134

Language Statements IAF 8.0 DML

END_EXECUTE

END_EXECUTE
Syntax
END_EXECUTE [/HANDLE=connect_handle] [writable_data_element[,...]]

Description
This statement allows a IAF Client to abort its currently executing stored procedure. This statement is intended for use when the stored procedure has returned a sufficient amount of row data to the Client, thereby making continued execution of the procedure unnecessary. This statement can be used in conjunction with RECEIVE_DATA in order to retrieve argument data from a stored procedure.

Qualifiers
/HANDLE=connect_handle

This qualifier allows you to specify the handle of the connection on which the stored procedure to abort is executing. The specified handle is the one that the CONNECT statement established for the connection. IAF searches the Clients list of current connections to determine if the given connect handle is valid for the current connection. If the handle is valid for a current connection, IAF aborts the stored procedure that is executing on that connection. If the handle is not valid for a current connection, IAF returns an error status in the %STATUS special variable. If the END_EXECUTE statement does not specify this qualifier, the default connect handle that the most recently executed CONNECT statement established. If no connection exists, IAF displays an error message. You can specify the connect handle via a constant or a variable.

Parameters
writable_data_element[,...]

This is one or more optional writable data elements (for example, variables, table fields, or parameters) to which the stored procedure is to return arguments. Note that unless the stored procedure traps the Clients

Language Statements IAF 8.0 DML

6-135

END_EXECUTE

END_EXECUTE request, the values of these data elements are undefined. For details on how a stored procedure can check for a Clients END_EXECUTE request, refer to this chapters description of the SEND_DATA statement.

Examples
END_EXECUTE /CONNECT=SALES END_EXECUTE /CONNECT=#LOOKUP #CUST_ID,#CUST_NAME,#CUST_PHONE

Related Topics
The following references contain information pertaining to the END_EXECUTE statement: This chapters discussions of the EXECUTE, CONNECT, DISCONNECT, RECEIVE_DATA, RECEIVE_TABLE, SEND_DATA, SEND_MESSAGE, and SEND_TABLE statements. The discussion of the %STATUS special variable in this manuals SPECIAL VARIABLES AND VALUE SYMBOLS chapter. The discussion of IAFs client/server environment in the IAF User Guide. The discussion of IAFs client/server environment in the IAF guide that applies to your operating system.

6-136

Language Statements IAF 8.0 DML

END_EXECUTE

END_EXECUTE
Syntax
END_EXECUTE[/HANDLE=connect_handle][writable_data_element[,...]]

Category
Client/Server environment.

Description
This statement allows a IAF Client to abort its currently executing stored procedure. This statement is intended for use when the stored procedure has returned a sufficient amount of row data to the Client, thereby making continued execution of the procedure unnecessary. This statement can be used in conjunction with RECEIVE_DATA in order to retrieve argument data from a stored procedure.

Qualifiers
/HANDLE=connect_handle

This qualifier allows you to specify the handle of the connection on which the stored procedure to abort is executing. The specified handle is the one that the CONNECT statement established for the connection. IAF searches the Client's list of current connections to determine if the given connect handle is valid for the current connection. If the handle is valid for a current connection, IAF aborts the stored procedure that is executing on that connection. If the handle is not valid for a current connection, IAF returns an error status in the %STATUS special variable. If the END_EXECUTE statement does not specify this qualifier, the default connect handle that the most recently executed CONNECT statement established. If no connection exists, IAF displays an error message. You can specify the connect handle via a constant or a variable.

Parameters
writable_data_element[,...]
Language Statements IAF 8.0 DML 6-137

END_EXECUTE

This is one, or more, optional, writable, data elements (for example, variables, table fields, or parameters) to which the stored procedure is to return arguments. Note that unless the stored procedure traps the Client's END_EXECUTE request, the values of these data elements are undefined. For details on how a stored procedure can check for a Client's END_EXECUTE request, refer to this chapter's description of the SEND_DATA statement.

Examples
END_EXECUTE /HANDLE=SALES END_EXECUTE /HANDLE=#LOOKUP #CUST_ID, #CUST_NAME,#CUST_PHONE

Related Topics
The following references contain information pertaining to the END_EXECUTE statement: This chapters discussions of the EXECUTE, CONNECT, DISCONNECT, RECEIVE_DATA, RECEIVE_TABLE, SEND_DATA, SEND_MESSAGE, and SEND_TABLE statements. The discussion of the %STATUS special variable in this manual's SPECIAL VARIABLES AND VALUE SYMBOLS chapter The discussion of IAF's client/server environment in the IAF User Guide The discussion of IAFs client/server environment in the IAF guide that applies to your operating system.

6-138

Language Statements IAF 8.0 DML

END_GTID

END_GTID
Syntax
END_GTID

Category
Data access

Description
This statement decrements the %GTID_LEVEL (Global Transaction Identifier Level) special variable. The START_GTID and END_GTID statements are used to group a set of related database transactions into one single logical transaction. All database transactions in the logical transaction are given the same transaction identifier. The START_GTID and END_GTID statements are permitted to be nested. The START_GTID statement starts a logical transaction and increments %GTID_LEVEL. When the %GTID_LEVEL special variable transitions from 0 to 1, a transaction identifier is generated. The END_GTID statement decrements the %GTID_LEVEL special variable. The %GTID special variable never goes below zero. When the %GTID_LEVEL special variable is 0 (no logical transaction in progress), the transaction identifiers normally generated for each database transaction are used as usual. While the %GTID_LEVEL is non-zero, transaction identifiers are taken from the transaction identifier that was generated when %GTID_LEVEL transitioned from 0 to 1, not from the transaction identifier that was generated when %TRANS_LEVEL transitioned from 0 to 1.

Related Topics
See also the START_GTID statement and the %GTID and %GTID_LEVEL special variables as well as the "IAF Transaction Identifiers" appendix of this manual. Transaction identifiers are logged to every table involved in a transaction that contains a table-field named GEM_TRANSACTION_ID Transaction identifiers are also loosely

Language Statements IAF 8.0 DML

6-139

END_GTID

related to the "Electronic Signature and Audit Record" feature. Transaction identifiers are logged to the GEM_SIGNATURE_AUDIT table and to the electronic signature audit log file. See the "Electronic Signature and Audit Record" appendix of this manual for more information.

6-140

Language Statements IAF 8.0 DML

END_SIGNAL_TO_STATUS

END_SIGNAL_TO_STATUS
Syntax
END_SIGNAL_TO_STATUS

Category
Program flow

Description
This statement indicates that IAF is to stop trapping signaled errors to the %STATUS special variable. IAF begins trapping signaled errors to the %STATUS variable only as a result of executing the BEGIN_SIGNAL_TO_STATUS statement.

Example
PROCEDURE_FORM CHECK_FOR_FILE (#FILE_NAME) ! This routine returns %NORMAL if the given file exists, and ! %FAILURE if it does not. ! BEGIN_SIGNAL_TO_STATUS OPEN_TEXT #FILE_NAME AS TEST_TAG END_SIGNAL_TO_STATUS \ IF (%STATUS=%NORMAL) CLOSE_TEXT TEST_TAG EXIT (%NORMAL) ELSE EXIT (%FAILURE) END_IF END_FORM

Related Topics
The following references contain information pertaining to the END_SIGNAL_TO_STATUS statement: This chapters discussion of the BEGIN_SIGNAL_TO_STATUS statement. The discussion of the %STATUS special variable in this manuals SPECIAL VARIABLES AND VALUE SYMBOLS chapter.

Language Statements IAF 8.0 DML

6-141

ERASE

ERASE
Syntax
ERASE [/qualifiers]

Category
Screen input and output

Description
This statement causes IAF to erase all or part of the window associated with the form in which execution of this statement takes place. IAF uses any given row and/or column information to determine the area to erase. Column and row values are relative to the form window (i.e. not the screen). If the ERASE statement does not include any row or column information, IAF erases the entire form window.

Qualifiers
The following qualifiers are valid for use with the ERASE statement:
/COL=column_number

This qualifier enables you to specify the starting column of the area to erase. Used alone, this qualifier causes IAF to erase a single column.
/END_COL=column_number

This qualifier enables you to specify the last column of the area to erase.
/END_ROW=row_number

This qualifier enables you to specify the last row of the area to erase.
/ROW=row_number

This qualifier enables you to specify the starting row of the area to erase. Used alone, this qualifier causes IAF to erase a single row.

Examples
ERASE /ROW=10 /END_ROW=12 ! Erase rows 10, 11, and 12 from all columns.

6-142

Language Statements IAF 8.0 DML

ERASE

ERASE /COL=2 /END_COL=3 ! Erase columns 2 and 3 in all rows. ERASE /ROW=1 /END_ROW=10 /COL=2 ! Erase rows 1-10, inclusive, in column 2. ERASE /COL=2 /END_COL=4 /ROW=1 ! Erase columns 2-4, inclusive, in row 1. ERASE /ROW=1 /END_ROW=10 /COL=2 /END_COL=4 ! Erase the rectangular area having the given corner ! coorDInates (/ROW=1 and /COL=2 specify the top left ! coordinate, and /END_ROW=10 and END_COL=4 specify the ! bottom right coordinate).

Language Statements IAF 8.0 DML

6-143

ERROR

ERROR
Syntax
ERROR [/qualifiers] error_text

or
ERROR

Category
Screen input and output

Description
This statement displays the specified error text in the error message display area at the base of the screen, or clears an existing error message from the area. If the ERROR statement includes an error text specification (error_text), and the error message display area already contains an error message, IAF displays a question mark (?) to the right of the error message to let the end user know that it has another error message to display. The end user can then press any key to display the underlying error message. If the ERROR includes a null string () instead of an error text specification, IAF clears the last error message that it displayed before executing the ERROR statement.

6-144

Language Statements IAF 8.0 DML

ERROR_TEXT

ERROR_TEXT
Syntax
ERROR_TEXT(error_no, flags, [,argument1[,argument2[,...]]])

Category
Screen input and output

Description
This statement supports arguments in error messages. IAF supports substitution of arguments for mask tokens at execution time. Argument substitution is done on a character-by-character basis. A message needs to include in its text as many tokens as arguments desired in the right place. A missing a token or argument will be ignored.

Language Statements IAF 8.0 DML

6-145

ERROR_TEXT

error_text

This is the text message that IAF is to display in the error message display area. The error text specification can be an expression. However, if it is an expression, it must be enclosed within parentheses.

Qualifiers
The following qualifiers are valid for use with the ERROR statement:
/BELL

This qualifier causes IAF is to trigger a system bell when executing the ERROR statement. This is the default behavior.
/CONFIRM

This qualifier causes IAF to display the given error message and then wait for end user input, confirming that the end user has seen the message, before removing the message from the screen. The difference between the /CONFIRM qualifier and the /WAIT qualifier is that the /CONFIRM qualifier causes the program to pause at the message display point as opposed to the next input or next message display (whichever comes first) as is the case with the /WAIT qualifier.
/NOBELL

This qualifier causes IAF not to trigger a system bell when executing the ERROR statement.
/NOWAIT

This qualifier causes IAF to forego the default waiting period associated with the ERROR statement. This means that IAF can overwrite the current error message with a subsequent error message without end user confirmation.
/TEXT_ONLY

This qualifier causes IAF to forego displaying %DMRMAN-EUSRERR with the given error message.

6-146

Language Statements IAF 8.0 DML

ERROR_TEXT

/WAIT

This qualifier causes IAF to honor the default waiting period associated with the ERROR statement. This means that IAF cannot overwrite the current error message with a subsequent error message without end user confirmation. The difference between the /WAIT qualifier and the /CONFIRM qualifier is that the /CONFIRM qualifier causes the program to pause at the message display point as opposed to the next input or next error message display (whichever comes first) as is the case with the /WAIT qualifier.

Examples
ERROR/BELL Invalid department number ERROR (No such customer: & #CUST_NO)

Related Topics
The following references contain information pertaining to the ERROR statement: This chapters discussion of the MESSAGE and PRINT statements. The discussion of the ERROR_TEXT built-in function in this manuals BUILT-IN FUNCTIONS chapter. The discussion of the %STATUS system variable in this manuals SPECIAL VARIABLES AND VALUE SYMBOLS chapter.

Language Statements IAF 8.0 DML

6-147

EXECUTE

EXECUTE
Syntax
EXECUTE [/HANDLE=connect_handle] [/NOWAIT] procedure_name [(arg1[,arg2[,...]])]

Category
Client/Server environment.

Description
This statement causes the Application Server to execute the specified stored procedure (procedure_name). The Application Server is identified by the connect_handle. Specify the connect_handle of an application opened via OPEN_APPLICATION and CONNECT statements. If a stored procedure includes a SEND_DATA statement and the server is waiting for a RECEIVE_DATA statement from the client, then any other execute statements will place a %ABORT value in the %STATUS symbol and the currently executing stored procedure stops executing. At that point the server will be ready to accept additional execute statements.

Qualifiers
/HANDLE=connect_handle

The specified connect_handle is one that the OPEN_APPLICATION statement specified for the application connection. This qualifier enables you to specify the handle of the connection on which the stored procedure execution is to take place. The specified handle is the one that the CONNECT statement established for the connection. IAF searches the Client's list of current connections to determine if the given connect handle is valid for a current connection. If the handle is valid for a current connection, IAF executes the stored procedure on that connection, unless execution of a stored procedure is already taking place on that connection. If this is the case, the EXECUTE statement aborts, and returns an error status in the %STATUS special variable.

6-148

Language Statements IAF 8.0 DML

EXECUTE

If the EXECUTE statement does not include this qualifier, the default connect handle is the handle that the most recently executed CONNECT statement specified. If no connection exists, IAF displays an error message. You can specify the connect handle via a constant or a variable.
/NOWAIT

This qualifier instructs the client to not wait for the stored procedure. By default, the client will wait for the stored procedure to complete. At completion, any stored procedure reference arguments will have been updated in the client. You might want to use the /NOWAIT qualifier when executing a long running stored procedure that does not return any information to the client. Or when running a stored procedure that uses several SEND_DATA statements to send data to the client. The client should then continue to execute RECEIVE_DATA statements to receive the data and finally use an END_EXECUTE to receive any returned reference arguments.

Parameters
procedure_name

Specifies the name of the procedure to execute. The stored procedure must exist in the database opened via the OPEN_APPLICATION statement. If the OPEN_APPLICATION statement does not include a database specification, IAF searches for the stored procedure in each database invoked by the application. The stored procedure name can be a predefined IAF stored procedure, or a stored procedure defined via the ADD option on the Data Definition Editor's Stored Procedure maintenance menu, or via the ADD PROCEDURE metadata command. Note that IAF searches serially through all database(s) associated with the connect handle and executes the first procedure if finds who's name matches the procedure name that the EXECUTE statement specifies. Therefore, if two or more procedures of the same name exist in different databases associated with the same application, IAF executes the procedure that resides in the first of the databases. For details regarding the predefined stored procedures, refer to this manual's PREDEFINED STORED PROCEDURES appendix. (arg1, arg2,..)
Language Statements IAF 8.0 DML 6-149

EXECUTE

You can optionally pass arguments to the stored procedure. Note that the stored procedure routing defines the passing mechanism (i.e. value or reference). For information on defining the passing mechanism for a stored procedure, refer to the DATA DICTIONARY chapter in the IAF System Reference Manual.

Examples
EXECUTE GEM_COMMIT() EXECUTE GET_CUSTOMER_DETAILS (#CUST_NO, #CUST_NAME) EXECUTE /HANDLE=MANU INIT()

Related Topics
The following references contain information pertaining to the RECEIVE_TABLE statement: This chapters discussions of the RECEIVE_DATA, SEND_TABLE, SEND_DATA, SEND_MESSAGE, EXECUTE, END_EXECUTE, CONNECT, and DISCONNECT statements. The discussion of the IAF Client/Server environment in the IAF User Guide and the IAF guide that applies to your operating system. The discussion of stored procedures in the chapter titled DATA DICTIONARY in the IAF System Reference Manual. The discussion of the ADD PROCEDURE metadata command in this manual's DML METADATA COMMANDS chapter The discussion of predefined stored procedures in this manuals PREDEFINED STORED PROCEDURES appendix.

6-150

Language Statements IAF 8.0 DML

EXIT

EXIT
Syntax
EXIT [(exit_status)]

Category
Program flow

Description
This statement causes IAF to immediately exit the current form, and is equivalent to branching to the end of the form. The EXIT statement can optionally specify an exit status. If it does, IAF places the exit status in the %STATUS special variable upon returning control to the calling form. If the EXIT statement does not specify an exit status, IAF places the %EXIT value symbol in %STATUS. IAF executes an implicit EXIT (%EXIT) statement if an end user presses the GM_EXIT key at any form input. Likewise, IAF executes an implicit EXIT (%BACK) statement if an end user presses the GM_BACK key at the first input in a form.
exit_status

This is a valid value symbol indicating the condition under which the form exit is taking place, and is the value that IAF places in the %STATUS special variable upon returning control to the calling form. For a list of the value symbols that the EXIT statement can specify, refer to this manuals SPECIAL VARIABLES AND VALUE SYMBOLS chapter. If the EXIT statement does not specify an exit status, IAF places the %EXIT value symbol in %STATUS.
A note regarding %EXIT_FORWARD:

An EXIT statement specifying the %EXIT_FORWARD value symbol as an exit status has the same effect as an end user pressing the GM_EXIT_FORWARD key. Therefore, the actual exit status depends upon the result of any remaining form processing that takes place. For details regarding the effect of exiting forward, refer to the discussion of the /EXIT_FORWARD block qualifier in this manuals BLOCKS AND BLOCK QUALIFIERS chapter.

Language Statements IAF 8.0 DML

6-151

EXIT

Examples
EXIT EXIT (%FAILURE)

Related Topics
The following reference contains information pertaining to the EXIT statement: The discussion of special variables and value symbols in this manuals SPECIAL VARIABLES AND VALUE SYMBOLS chapter.

6-152

Language Statements IAF 8.0 DML

EXPORT

EXPORT
Syntax
EXPORT [/ARCHIVE=archive-file-specification] [/ASCII] [/BINARY] [/CHARACTER_SET=character-set] [/COMMIT_RATE=n] [/CSV] [/DATA] [/FAILURE=(failure-dml)] [/FROM=database-handle] [/LOG=log-file-specification] [/METADATA=metadata-list] [/NOAUDIT] [/NODATA] [/NOLOG] [/NOMETADATA] [/NOSIGN] [/NOSTATUS] [/SIGN] [/STATUS] [/SUCCESS=(success-dml)] [/TABLES="wildcard-tablename, wildcard-tablename, ..."] [/TO=database-handle] [/VERBOSE]

Category
Data Access.

Description
The EXPORT statement provides both the DML programmer and the system administrator with the means to export database table-field data
Language Statements IAF 8.0 DML 6-153

EXPORT

directly from a source database to a target ("archive") database or to an intermediate export archive file. Datatype, global field, table-field, table and index metadata referenced by table-fields in the selected tables may also be exported at the same time the table-field data is exported. When the EXPORT statement is executed with no qualifiers, an interactive dialog is presented. See also the closely related IMPORT statement.

Implicit Actions
An export archive file is created when the /ARCHIVE qualifier is specified. An export log file is always produced. Use the /LOG qualifier to control where and under what filename the log file is produced. When no qualifiers are specified, the EXPORT statement brings up an interactive dialog containing various input fields for the user to fill in. The user may use the LIST-OF-VALUES key when prompted for the list of database tables to be exported.

Special Considerations
When metadata is copied from a source database to a target database, only that metadata which does not already exist in the target database is copied. When the /METADATA qualifier is used without any qualifier value or when MINIMUM is selected at the metadata prompt in the interactive dialog, only data-type, global-field, table-field, table, and index metadata are copied; only those global fields referenced by table-fields contained in the selected tables are copied; only data-types referenced by global-fields referenced by table-fields contained in the selected tables are copied; and only indices for the selected tables are copied. Note that since EXPORT permits you the freedom to select individual metadata objects to be exported, and import permits you the freedom to select individual metadata objects to be imported, it is possible to export or import less metadata than will actually be required during an import process when the target database during the import processing is missing required metadata. For instance, if you export only ROLE_USERS, but not ROLES during the export process (or import only ROLE_USERS during the import process), it is possible for the target database to not contain the roles that are referenced by the imported ROLE_USERS (because theyre not already in the database for whatever reason and you either did not export them or you did not import them). In this case, the importation of one or more ROLE_USERS will fail. If you choose to
6-154 Language Statements IAF 8.0 DML

EXPORT

export or import less than ALL metadata, you must understand which metadata depends upon other metadata. When you export and import ALL metadata, the metadata is both available to be imported when needed and is imported in the proper order to satisfy such metadata dependencies. When both metadata and data are copied from a source database to a target database, if any of the metadata which EXPORT attempts to add to the target database already exists, then an intermediate cross-check phase occurs. During this phase each table in the target database is checked to ensure: The tables that are imported in the table-field data import phase are the intersection of the selected source tables and the correspondingly present target database tables. If a selected source table is not present in the target database, its table-field data is not imported. Warning messages are logged to the log file for each selected source table that is not present in the target database and for each target table that is not present in the source database or export archive file. The table-fields that are imported in the table-field data import phase are the intersection of the table-fields present in the selected source tables and corresponding target database tables. Of the tables that are to be imported in the table-field data import phase, both source and target tables must have at least one same named table-field in common. A warning message is logged to the log file for each source table that does not have at least one tablefield in common with its corresponding target database table (and then no table-field data for the tables in question is subsequently imported). All PID table-fields in each target database table to be imported must be present in the corresponding table within the source database or export archive file. An error message is logged to the log file for each missing PID table-field. These are fatal errors that cause the import to fail at the end of the metadata cross check phase. A warning message is logged to the log file for each table-field in the target database that is computed or read-only if the corresponding table-field in the source database or export archive file is NOT also computed or read-only. Table-field data for computed and read-only target database table-fields is not and cannot be imported. If both source and target are computed or readonly, then they are silently ignored.

Language Statements IAF 8.0 DML

6-155

EXPORT

The native data type category and scale of each source table-field to be imported in the table-field copy phase must match that of the same named target table-field. An error message is logged to the log file for each mismatch. Data type category and scale mismatches are fatal errors that cause the import to fail at the end of the metadata cross check phase. For the purposes of importing table-field data, GEM_ARCHIVE_FLAG and GEM_TRANSACTION_ID tablefields are not read-only. The contents of GEM_ARCHIVE_FLAG and GEM_TRANSACTION_ID table-fields are copied from source to target as-is without modification. In particular, the transaction identifiers will be those from the source table and not be reset to newly generated values when the target row is updated in place or added to the target table. This permits EXPORT / IMPORT to be used to create an archival copy of a database (which is its primary intended purpose). Note: IAF V7.0 required the source and target database tables to have the same number of table-fields. This is no longer a requirement. The cross-check phase also occurs when only data is copied from a source database to a target database. In this case the "cross-check" phase occurs before the table-field data is copied. Both the source and target databases may have been invoked using any database engine supported by IAF, including engine SERVER. When source and target engine types differ, incompatible metadata attributes are automatically dropped on a best-effort basis. The most common such attributes are Oracle table-spaces. An Oracle table-space will be dropped when both the source and target databases are Oracle databases and the target database does not contain the specified tablespace. When copying metadata to an RMS database, all newly created tables are created as DYNAMIC tables.

6-156

Language Statements IAF 8.0 DML

EXPORT

Qualifiers
You can append the following qualifiers to the EXPORT statement: /ARCHIVE=archive-file-specification This qualifier indicates that IAF is to produce an export archive file with the specified filename. The default file type for IAF export archive files is ".gem_export." The archive qualifier value may be a quoted string literal, variable, special variable, table-field, function or an expression. The /ARCHIVE qualifier is incompatible with the /TO qualifier. /ASCII This qualifier indicates that the export archive file is to be produced in ASCII format rather than BINARY format. ASCII export archive files are much larger than BINARY export archive files. You should only produce an ASCII export archive file when you need to transport the file through an environment, which is hostile to binary data. /BINARY This qualifier indicates that the export archive file is to be produced in BINARY format rather than ASCII format. This is the default export archive format.

Language Statements IAF 8.0 DML

6-157

EXPORT

/CHARACTER_SET=character-set Example
/CHARACTER_SET=UTF-8

This optional qualifier indicates the character-set with which the export archive is to be written. Character-set can be a quoted literal, a variable, a function, a table-field or an expression in parentheses. When this qualifier is used, IAF converts all textual data that is stored in the export archive from the character-set specified with the GEM_CHARACTER_SET SCV to the character-set specified with this qualifier. By default no characterset conversion occurs and the export archive is written using the character-set specified with the GEM_CHARACTER_SET SCV. /COMMIT_RATE=numeric-expression This qualifier indicates the number of records that IAF is to process before committing the current transaction. The numeric expression's value must be an integer greater than zero. IAF commits any records that are not an integral number of the commit rate when the record stream is exhausted. For example, if a given record stream retrieves 14 records and the commit rate that this qualifier specifies is 5, IAF commits a set of five records with the first transaction, a set of five records with the second transaction, and a set of four records with the subsequent transaction. Note that the commit rate is applied on a per-table basis. A commit also occurs after all records have been fetched from each table, regardless of the commit rate value. /CSV This optional qualifier indicates that a comma separated variable (CSV) text file is to be produced. When the CSV qualifier is used, the syntax and functionality of the EXPORT statement changes significantly. Please refer to the description of the EXPORT/CSV statement for details. /DATA This qualifier indicates that table-field data is to be exported from the specified tables. By default, no table-field data is exported. /FAILURE=(failure-dml) This qualifier enables you to specify a DML statement that IAF is to execute if the export fails. For a list of DML statements that the /FAILURE qualifier can specify, refer to this manual's EXECUTING DML STATEMENTS VIA QUALIFIERS appendix.
6-158 Language Statements IAF 8.0 DML

EXPORT

/FROM=database-handle /LOG=log-file-specification Example

/LOG=sys$manager:my_database_export.log

This qualifier indicates that EXPORT is to produce a log file with the specified filename. Log-file-specification may be a quoted string literal, variable, special variable, table-field, function or an expression. The default file specification for EXPORT files is "gem_export.log." The default for EXPORT is to create a log file. Use the /NOLOG qualifier to suppress the creation of the log file. /METADATA=metadata-list Example
/METADATA=ALL

This optional qualifier indicates that IAF metadata should be exported. If the /METADATA qualifier is used alone without any qualifier value, then only data-type, global field, index, table and table-field metadata objects are exported from the specified tables. Metadata-list can be a quoted literal, a variable, a function, a table-field or an expression in parentheses. When metadata-list is specified, it contains a comma separated list of metadata objects that are to be exported. The metadata object names that can be specified are as follows: ALL, CLASSES, DATATYPES, DOMAINS, FACILITIES, FACILITY_LINKS, FACILITY_ROLES, FIELDS, INDICES, MENU_TAGS, MESSAGES, PARAMETERS, PROCEDURES, ROLE_ADMINS, ROLE_MANAGER, ROLE_USERS, ROLES, TABLES, TIME_TRIGGERS, TRIGGERS, VIEWS. ALL indicates that all metadata objects are to be exported. Each metadata object name may also be prefixed with NO (for example, NOCLASSES) to indicate a metadata object that is not to be exported. Metadata object names are processed in the order specified. To export all except a subset of metadata objects specify ALL followed by each of the objects that are to be excluded prefixed with NO (for example, ALL,NOROLES,NOROLE_ADMINS,NOROLE_USERS). /METADATA= NOALL is the same as omitting the /METADATA qualifier altogether. /NODATA /NOLOG

Language Statements IAF 8.0 DML

6-159

EXPORT

This qualifier indicates that EXPORT is not to produce a log file. The default action for EXPORT is to create a log file. Use this qualifier to suppress the creation of a log file. /NOMETADATA This qualifier indicates that metadata is not to be exported from the specified tables. This is the default. /NOSIGN This qualifier indicates that the export archive file is not to have a digest appended at the end of the archive file. This is the default. /NOSTATUS This qualifier indicates that IAF is not to display a status window. /SIGN This qualifier indicates that the export archive file is to have a digest appended to the end of the file. The digest can then later be checked with the IMPORT /CHECK_ONLY statement. This permits the integrity of the export archive to be checked and is useful when export archives are to be transferred over unreliable communication channels. /STATUS This qualifier indicates that IAF is to display a status window across the screen during each phase of the export processing. A second status window is also displayed as each table is processed if the given tables processing phase exceeds 10 seconds. However, the second status window does not display during the tables record selection phase, regardless of the duration of the record selection phase. /SUCCESS=(success_dml) This qualifier enables you to specify a DML statement that IAF is to execute if the export succeeds. For a list of DML statements that the /SUCCESS qualifier can specify, refer to this manual's EXECUTING DML STATEMENTS VIA QUALIFIERS appendix. /TABLES="wildcard-tablename, wildcard-tablename, ..." This qualifier indicates the database tables that are to be exported. This is a comma-separated list of wildcard table names. The "*" and "%"

6-160

Language Statements IAF 8.0 DML

EXPORT

wildcard characters may be used within each table name to indicate a set of tables matching a wildcard pattern. ." The tables qualifier value may be a quoted string literal, variable, special variable, table-field, function or an expression. /TO=database_handle /VERBOSE This optional qualifier causes EXPORT to keep the user informed of the progress of the export operation in verbose detail. For instance, rather than just informing the user that it is exporting an entire set of metadata objects (such as tables), EXPORT will inform the user each and every time it exports an individual metadata object (such as a particular table).

Language Statements IAF 8.0 DML

6-161

EXPORT

Exit Status
The EXPORT statement exits with %SUCCESS when the export process succeeds and %FAILURE when it fails. You may use the /SUCCESS and /FAILURE qualifiers to "trap" these exits or you may explicitly check the value of the %STATUS variable.

6-162

Language Statements IAF 8.0 DML

EXPORT/CSV

EXPORT/CSV
Syntax
EXPORT/CSV [/ALWAYS_QUOTE] [/CHARACTER_SET=character-set] [/DOUBLE_QUOTE] [/ESCAPE_CHARACTER=escape-character] [/FAILURE=(dml-statement)] [/FIELD_SEPARATOR=field-separator] [/FIELDS=field-list] [/FROM=database-handle.table-name] [/LOG=log-file-specification] [/METADATA=metadata-list] [/QUOTE_CHARACTER=quote-character] [/STATUS] [/SUCCESS=(dml-statement)] [/TO=CSV-file-specification]

Category
Data Access.

Description
The EXPORT/CSV statement is used to export the contents of a single table to a comma separated variable (CSV) text file. Also see the description of the IMPORT/CSV statement.

Implicit Actions
When no qualifiers (other than /CSV) are specified, the EXPORT/CSV statement brings up an interactive dialog containing various input fields for the user to fill in. The user may use the LIST-OF-VALUES key when prompted for the table to be exported and when prompted for the tablefields to be exported. By default, all table-fields are selected to be exported. The user must delete those table-fields that are not to be

Language Statements IAF 8.0 DML

6-163

EXPORT/CSV

exported from the list presented. Wildcard table-field names may be entered. A blank entry for the escape character or the quote character means no escape character and no quote character respectively. Both single characters and decimal character code values may be entered for the escape character, the field separator character and the quote character.

Qualifiers
/ALWAYS_QUOTE This optional qualifier when specified causes all fields to be quoted. /CHARACTER_SET=character-set Example
/CHARACTER_SET=UTF-8

This optional qualifier indicates the character-set with which the CSV file is to be written. Character-set can be a quoted literal, a variable, a function, a table-field or an expression in parentheses. When this qualifier is used, EXPORT/CSV converts all data that is stored into the CSV file from the character-set specified with the GEM_CHARACTER_SET SCV to the character-set specified with this qualifier. By default no characterset conversion occurs and the CSV file is written using the character-set specified with the GEM_CHARACTER_SET SCV. /COMMIT_RATE=numeric-expression Example
/COMMIT_RATE=100

This qualifier indicates the number of records that EXPORT/CSV is to process before committing the current transaction. The numeric expression's value must be an integer greater than zero. EXPORT/CSV commits any records that are not an integral number of the commit rate when the record stream is exhausted. For example, if a given record stream retrieves 14 records and the commit rate that this qualifier specifies is 5, EXPORT/CSV commits a set of five records with the first transaction, a set of five records with the second transaction, and a set of four records with the subsequent transaction. A commit also occurs after all records have been retrieved from the table, regardless of the commit rate value.

6-164

Language Statements IAF 8.0 DML

EXPORT/CSV

/CSV This qualifier is required. It indicates that a comma separated variable (CSV) text file is to be produced. If this qualifier is not specified, the syntax and functionality of the EXPORT statement changes significantly. Please refer to the description of the regular EXPORT statement for details. /DOUBLE_QUOTE This optional qualifier when specified causes all quote characters contained within the field data to be replaced with two quote characters within the CSV file. /ESCAPE_CHARACTER=escape-character Example
/ESCAPE_CHARACTER=/

This optional qualifier specifies the character that is used to escape the field separator character when it appears within field data. Escapecharacter can be a quoted literal, a variable, a function, a table-field or an expression in parentheses. Either a single one byte character may be specified or a two or more byte decimal character code may be specified. When specifying a decimal character code rather than the actual character, if the decimal character code is less than 10, prefix it with zeros. For instance, specify 008 instead of 8. Only decimal character codes 001 through 255 are valid. The most often used escape character is the forward slash (/) character. The escape character is only used when the field data is not quoted. The default if the /ESCAPE_CHARACTER qualifier is not used is no escape character. /ESCAPE_CHARACTER= (null string; explicit no escape character) is the same as no escape character. /FAILURE=(dml-statement) Example
/FAILURE=(GOTO EXPORT_FAILED)

This optional qualifier specifies a DML statement that IAF is to execute after the EXPORT operation fails for any reason. For a list of DML statements that the /FAILURE qualifier can execute, please refer to the appendix on Executing DML Statements Via Qualifiers section of this manual.

Language Statements IAF 8.0 DML

6-165

EXPORT/CSV

/FIELD_SEPARATOR=field-separator Example
/FIELD_SEPARATOR=,

This optional qualifier specifies the character that is used to separate fields within each row in the CSV file. Field-separator can be a quoted literal, a variable, a function, a table-field or an expression in parentheses. Either a single one byte character may be specified or a two or more byte decimal character code may be specified. When specifying a decimal character code rather than the actual character, if the decimal character code is less than 10, prefix it with zeros. For instance, specify 008 instead of 8. Only decimal character codes 001 through 255 are valid. The most often used field separator character is the comma (,) character. The default if the /FIELD_SEPARATOR qualifier is not used is to use a comma , character. Because a field separator character is mandatory, /FIELD_SEPARATOR= (null string; explicit no field separator character) is not permitted. /FIELDS=field-list Example
/FIELDS=MEMBERS,USERS,RENT*,UNIT_%%%_MEASURE,A*B*C

This optional qualifier specifies a comma separated list of table-fields to be exported. Fields can be a quoted literal, a variable, a function, a tablefield or an expression in parentheses. The * and % wildcard characters may be used. By default, all table-fields in the table are exported (/FIELDS=*). /FROM=[database-handle.]table-name Example
/FROM=FIN.UNITS_OF_MEASURE

This required qualifier specifies the name of the table to be exported. The qualifier value can be an unquoted literal (as shown above in the example), a quoted literal, a variable, a function, a table-field or an expression in parentheses. This is a required qualifier. The databasehandle. portion is optional and defaults to the database-handle of the default database.

6-166

Language Statements IAF 8.0 DML

EXPORT/CSV

/LOG=log-file-specification Example
/LOG=sys$manager:my_database_export.log

This qualifier indicates that EXPORT/CSV is to produce a log file with the specified filename. Log-file-specification may be a quoted string literal, variable, special variable, table-field, function or an expression. The default file specification for EXPORT/CSV log files is "gem_export.log." The default for EXPORT/CSV is not to create a log file. Use this qualifier if you would like a log file created. /METADATA This optional qualifier specifies that the list of table-fields exported is to be written to the first row of the CSV file as a field-separator character separated list. When the /ALWAYS_QUOTE qualifier is also specified, each table-field name in the table-field list is quoted with the quote character -- unless /QUOTE_CHARACTER= (null string; explicit no quote character) is also specified. /NOLOG This qualifier indicates that EXPORT/CSV is not to produce a log file. This is the default action for EXPORT/CSV. /NOMETADATA This optional qualifier specifies that the list of table-fields exported is NOT to be written to the first row of the CSV file. This is the default. /NOSTATUS This optional qualifier indicates that EXPORT/CSV is not to display a status window as the table rows are written to the CSV file. This is the default. /QUOTE_CHARACTER=quote-character Example
/QUOTE_CHARACTER=

This optional qualifier specifies the character that is used to either quote fields that contain the field separator character when it appears within field data or to always quote all field data when the /ALWAYS_QUOTE qualifier is used. Quote-character can be a quoted literal, a variable, a

Language Statements IAF 8.0 DML

6-167

EXPORT/CSV

function, a table-field or an expression in parentheses. Either a single one byte character may be specified or a two or more byte decimal character code may be specified. When specifying a decimal character code rather than the actual character, if the decimal character code is less than 10, prefix it with zeros. For instance, specify 008 instead of 8. Only decimal character codes 001 through 255 are valid. The most often used quote character is the double-quote () character. The default quote character if the /QUOTE_CHARACTER qualifier is not used is the double quote character. Specify /QUOTE_CHARACTER= (null string; explicit no quote character) to indicate that no quoting is to be performed. /SUCCESS=(success-dml) Example
/SUCCESS=(GOTO EXPORT_SUCCEEDED)

This optional qualifier specifies the DML statement that IAF is to execute if the EXPORT fails for any reason. For a list of DML statements that the /SUCCESS qualifier can execute, please refer to the appendix on EXECUTING DML STATEMENTS VIA QUALIFIERS in the IAF Data Manipulation Language manual. /STATUS This optional qualifier indicates that EXPORT/CSV is to display a status window across the screen as the table rows are written to the CSV file. /SUCCESS=(success-dml) Example
/SUCCESS=(GOTO EXPORT_SUCCEEDED)

/TO=CSV-file-specification Example
/TO=movies.csv

This optional qualifier specifies the file specification of the CSV file to be written. CSV-file-specification can be a quoted literal, a variable, a function, a table-field or an expression in parentheses. The default CSV file specification is the name of the table in lowercase plus a file-type of .csv.

6-168

Language Statements IAF 8.0 DML

EXPORT/CSV

Exit Status
After the EXPORT/CSV statement executes, the special variable %STATUS is set to one of the following values: %SUCCESS if the export succeeded. %FAILURE if the export failed. %EXIT if EXPORT/CSV was specified with no other qualifiers, an interactive dialog with the user occurred, and the user hit the GM_EXIT key. %BACK if EXPORT/CSV was specified with no other qualifiers, an interactive dialog with the user occurred, and the user hit the GM_BACK key at the first prompt.

Language Statements IAF 8.0 DML

6-169

EXPORT/XML

EXPORT/XML
Syntax
EXPORT/XML & [/FROM=database-tag] & [/FROM=database-tag.table-name] & [/FROM=stream:] & [/FROM=stream:table-name] & [/TABLE=table-name] & /TARGET=target

Category
Data Access

Description
This statement exports a single table from a database to a Microsoft ADO.net XML data table format data stream.

Qualifiers
The following qualifiers are valid for use with the EXPORT/XML statement. /FROM= This qualifier specifies the database tag name of the database from which to export the table. If a database tag name is not specified, then the default database is used. This syntax of this qualifier is extremely flexible. It can also be used to specify the table name (database-tag.table-name) or to specify the name of an already started stream from which to obtain the data to export (stream: or stream:table-name). By default all rows in the table are exported. By specifying the name of an already started stream, one can export less than the full table.

6-170

Language Statements IAF 8.0 DML

EXPORT/XML

/TABLE This qualifier specifies the name of the table to be exported. This overrides any table name mentioned in the /FROM qualifier. /TARGET This qualifier specifies a destination in which to place the XML data stream. For example, a text string variable.

Related Topics
See also the IMPORT/XML statement.

Language Statements IAF 8.0 DML

6-171

EXTERNAL

EXTERNAL
Syntax
EXTERNAL file_spec routine_name [function_return_value] [(argument1[,argument2[,...]])]

Category
Miscellaneous

Description
This statement declares an external third generation language (3GL) routine that the DML program containing this statement will subsequently perform via the CALL statement. The EXTERNAL statement is a declaration statement. Therefore, it performs no implicit action, but specifies the external file holding the routine, the datatype of any value that it returns, and the passing mechanism to use for each argument that it accepts (if any). Each routine that a CALL statement references must have a preceding EXTERNAL declaration.
file_spec

This is the name of the shareable image that contains the external routine. This must be a quoted literal and must specify an executable file. In casesensitive environments (i.e. UNIX, MPE/iX), be sure to use the proper case for the desired shareable image.
routine_name

This is the name of the external routine, and must be a valid symbol. The specified shareable image file (see file_spec above) must contain the routine. IAF is case-insensitive relative to external routine names. However, it is important for the EXTERNAL statement to specify the routine name in the case in which the 3GL interface expects to receive it.

6-172

Language Statements IAF 8.0 DML

EXTERNAL

function_return_value

This is one of the following keywords indicating the datatype of the routines return value. Keyword WORD.V LONG.V FFLOAT.V DFLOAT.V GFLOAT.V 16 bit integer 32 bit integer 32 bit floating point 64 bit floating point 64 bit floating point Datatype

IAF uses LONG.V if you do not specify a return value datatype. IAF stores the return value in the %STATUS special variable regardless of its datatype (e.g. if the routine returns a floating point value, IAF stores a floating point number in the %STATUS variable).
(argument1[,argument2[,...]])

This indicates the datatype and passing mechanism for each of the arguments that the external routine accepts, and can be one of the keywords that the following table lists. Keyword int16.r int16.v int16 WORD.V WORD.R LONG.V LONG.R FFLOAT.V FFLOAT.R DFLOAT.V Datatype and Passing Mechanism 16-bit signed integer by address 16-bit signed integer by value 16-bit signed integer by value 16 bit integer by value (obsolete) 16 bit integer by reference (obsolete) 32 bit integer by value 32 bit integer by reference 32 bit floating point by value 32 bit floating point by reference 64 bit floating point by value

Language Statements IAF 8.0 DML

6-173

EXTERNAL

Keyword DFLOAT.R GFLOAT.V GFLOAT.R DSTRING.D DSTRING.R ADT.R

Datatype and Passing Mechanism 64 bit floating point by reference 64 bit floating point by value 64 bit floating point by reference Dynamic string by descriptor Dynamic string by reference Quadword binary date/time by reference

If you do not explicitly specify a datatype and passing mechanism, the default is DSTRING.D (dynamic string by descriptor).

Examples
EXTERNAL CHECKS_AND_BALANCES check_digit EXTERNAL SALES_CALCULATIONS SALES_PREDICTION (FLOAT.R,FLOAT.R,FLOAT.R,DSTRING.D) EXTERNAL math_library Nth_Root (FLOAT.R,FLOAT.R,FLOAT.R) PROCEDURE_FORM CHECK (#OUTPUT) EXTERNAL CHECK_LOG CHECK (DSTRING.R) #OUTPUT=LEFT(#OUTPUT & STRING(40,32),40) ! Pad or truncate string to 40 characters long. In this ! example, an agreement exists between this form and the ! called routine that the string length is 40 characters. CALL CHECK (#OUTPUT) END_FORM PROCEDURE_FORM CHECK (#OUTPUT) EXTERNAL CHECK_LOG CHECK (DSTRING.R, LONG.R) CALL CHECK (#OUTPUT, LEN(#OUTPUT)) ! In this example, the second argument is the length of the ! string END_FORM

Related Topics
The following references contain information pertaining to the EXTERNAL statement: This chapters discussion of the CALL statement.

6-174

Language Statements IAF 8.0 DML

EXTERNAL

The discussion on building and using external routines in the IAF guide that applies to your operating system.

Language Statements IAF 8.0 DML

6-175

FETCH

FETCH
Syntax
FETCH stream_name [/qualifiers]

Category
Data access

Description
This statement causes IAF to retrieve the next record from the specified stream (stream_name), and place the retrieved record in the user buffer associated with the stream. Once IAF retrieves the last record in the stream, any subsequent FETCH statement causes IAF to return an error. You can determine the success or failure of a FETCH statement by testing the %STATUS special variable. If the FETCH statement executes successfully, the value of %STATUS is %NORMAL. Otherwise, the value of %STATUS is %FAILURE.
stream_name

This is the name of the stream from which IAF is to retrieve the next record, and must be a valid symbol. Various DML statements can cause IAF to begin a stream. These statements include the START_STREAM and FIND statements. The /TABLE form qualifier also causes IAF to begin a stream. For details on the START_STREAM and FIND statements, refer to their descriptions in this chapter. For details on the /TABLE form qualifier, refer to this manuals FORMS AND FORM QUALIFIERS chapter. For details on record streams, refer to the discussion of record streams and buffer management in the IAF Users Guide.

Qualifiers
The following qualifiers are valid for use with the FETCH statement:
/FAILURE=(dml_statement)

This qualifier enables you to specify a DML statement that IAF is to execute if the FETCH statement fails (i.e. there are no records left to fetch from the stream).

6-176

Language Statements IAF 8.0 DML

FETCH

/SUCCESS=(dml_statement)

This qualifier enables you to specify a DML statement that IAF is to execute if the FETCH statement succeeds (i.e. IAF retrieves a record).

Examples
START_STREAM ORDERS . . . FETCH ORDERS & /SUCCESS=(SALES_ORDERS(DELETE_FLAG)=Y) & /FAILURE=(EXIT) START_STREAM PARTS . . . WHILE (1) FETCH PARTS /FAILURE=(CONTINUE OUT) . . . process the record . . . END_WHILE

Related Topics
The following references contain information pertaining to the FETCH statement: This chapters discussion of the FIND and START_STREAM statements. The discussion of the /TABLE form qualifier in this manuals FORMS AND FORM QUALIFIERS chapter. The discussion of record streams and buffer management in the IAF Users Guide.

Language Statements IAF 8.0 DML

6-177

FILES

FILES
Syntax
FILES [/qualifiers] [file_spec]

Category
Utilities and program development

Description
This statement invokes IAFs File Manager utility. Executing the FILES statement with a file specification (file_spec) causes IAF to display a selectable list of all files matching the given specification. Selecting a file from the list causes IAF to display the File Processing menu or the Program Processing menu (depending on the type of file you selected), which contains options enabling you to perform a variety of functions. Executing the FILES statement without a file specification causes IAF to display the Files Maintenance menu, which contains options enabling you to specify the type of file you wish to review. Once you select a file type option, IAF displays a selectable list of files of the given type. For details on the File Manager utility, refer to the IAF System Reference Manual.
file_spec

This is a file specification indicating the file(s) IAF is to display in a selectable list in the File Manager. Including a file specification with the FILES statement causes IAF to bypass the Files Maintenance menu and immediately display any matching file(s) in a selectable list. The specification can include the wildcard character, *, to represent zero or more unknown characters, and can also include operating system dependent wildcard characters.

6-178

Language Statements IAF 8.0 DML

FILES

Qualifiers
The following table lists the qualifiers that are valid for use with the FILES statement, according to the functions they control. Function File List Availability File List Format /NOQUERY /DATE /DATE_TIME /FILE_DEVIC E File List Functionality File Operation /NOCREATE /CHECK /COMPILE_O NLY /DELETE_ON LY File Operation Details /BATCH /COPIES Menu Option Display /NOCOMPILE /NODISPLAY /NOEDIT
File List Availability

Qualifiers /QUERY /FILE_DIRECTO RY /FILE_EXTENSI ON /FILE_NAME /NODELETE /DISPLAY_ONL Y /EDIT_ONLY /PORT_ONLY /FORM_TYPE /LOG /NOPERFORM /NOPORT /NOPRINT /NOREDRAW /NORENAME /QUEUE /PRINT_ONLY /FILE_NODE /FILE_VERSI ON /SIZE

The following mutually exclusive qualifiers enable you to specify whether or not the selectable file list is to be available.
/NOQUERY

Language Statements IAF 8.0 DML

6-179

FILES

This qualifier indicates that IAF is not to display the selectable file list. This qualifier is valid for use only if the FILES statement also includes a file specification, and the /COMPILE_ONLY, /DELETE_ONLY, /DISPLAY_ONLY, /EDIT_ONLY, or /PRINT_ONLY qualifier. Specifying /NOQUERY without specifying a file specification cause IAF to display an error message. Specifying /NOQUERY with a file specification but without one of the qualifiers mentioned above causes IAF to ignore the /NOQUERY qualifier.
/QUERY

This qualifier indicates that IAF is to display the selectable file list.

6-180

Language Statements IAF 8.0 DML

FILES

File List Format

The following qualifiers enable you to specify the format of the selectable file list.
/DATE

This qualifier causes IAF to display the creation date of each file in the list. IAF displays No Access for any file still under creation or residing in a directory that IAF cannot access due to insufficient privileges.
/DATE_TIME

This qualifier causes IAF to display the creation date and time of each file in the list. IAF displays No Accessfor any file still under creation or residing in a directory that IAF cannot access due to insufficient privileges. This qualifier overrides the /DATE qualifier (see above).
/FILE_DIRECTORY

This qualifier causes IAF to display the name of the directory in which each file resides if your operating system supports this behavior.
/FILE_DEVICE

This qualifier causes IAF to display the name of the device on which each file resides if your operating system supports this behavior.
/FILE_EXTENSION

This qualifier causes IAF to display each files file extension (filetype) if your operating system supports this behavior.
/FILE_NAME

This qualifier causes IAF to display each files name.

/FILE_NODE

This qualifier causes IAF to display each files node name if your operating system supports this behavior.
/FILE_VERSION

This qualifier causes IAF to display each files version number if your operating system supports this behavior.

Language Statements IAF 8.0 DML

6-181

FILES

/SIZE

This qualifier causes IAF to display each files size. By default, the file list display includes a filename, file extension, and file directory for each file.
File List Functionality

The following qualifiers limit the functionality of the selectable file list.
/NOCREATE

This qualifier disallows the creation of new files. If the FILES statement does not include this qualifier, pressing the GM_INSERT_ROW key causes IAF to invoke the default text editor to facilitate creating a new file. The default text editor is the one that the GEM_EDITOR System Customization Variable (SCV) specifies, if defined. If the GEM_EDITOR SCV is not defined, IAF invokes the designated default editor for your operating system. For details regarding the default editor for your operating system, refer to the IAF guide that applies to your operating system.
/NODELETE

This qualifier disallows the deletion of files. If the FILES statement does not include this qualifier, pressing the GM_DELETE_ROW key causes IAF to delete the currently selected file after confirming that deletion should proceed.
File Operation

The following qualifiers enable you to specify the operation(s) that IAF is to perform for the specified file(s), and are mutually exclusive except for the /CHECK and /COMPILE_ONLY qualifiers, which can be used together. These qualifiers are valid for use only if the FILES statement includes a file specification. If the FILES statement includes a file specification and the /NOQUERY qualifier (see above), IAF immediately performs the specified operation(s) on any files that match the specification. If the FILES statement includes a file specification without the /NOQUERY qualifier, IAF displays any files that match the specification in a selectable file list, and performs the specified operation(s) on the file that you select from the list. If the FILES statement does not include a file specification, IAF displays an error message.
/CHECK
6-182 Language Statements IAF 8.0 DML

FILES

This qualifier causes IAF to perform the same compilation checks that it performs when executing the COMPILE/CHECK statement, and is intended for use with the /COMPILE_ONLY qualifier. For details on the COMPILE/CHECK statement, refer to this chapters description of the COMPILE statement.
/COMPILE_ONLY[=directory_spec]

This qualifier causes IAF to compile the specified file(s), thereby producing an executable image for each file. Including a directory specification (directory_spec) with the /COMPILE_ONLY qualifier causes IAF to place the executable files in the specified directory. If the /COMPILE_ONLY qualifier does not include a directory specification, IAF places the executable files in the current default directory.
/DELETE_ONLY

This qualifier causes IAF to delete the specified file(s).

/DISPLAY_ONLY[=screen_width_value]

This qualifier causes IAF to display the contents of the specified file(s), and can optionally include a screen width value of 80 or 132 to indicate the number of columns to use for the display. By default, IAF uses 132column mode for a particular file if any line in the file contains more than 80 characters, or 80-column mode, otherwise. Specifying 80 as the screen width value causes IAF to truncate to 80 characters any lines containing more than 80 characters. If a file contains more lines than a single screen can accommodate, you can use the GM_NEXT_SCREEN and GM_PREV_SCREEN keys to move from one screen of file data to another. If you are displaying more than one file, you can use the GM_CR, GM_ENTER, or GM_EXIT_FORWARD key to view the next file, if there is one, or to exit the FILES statement if there are no additional files to display.
/EDIT_ONLY

This qualifier causes IAF to invoke the default text editor and load the specified file(s) for editing. The default text editor is the one that the GEM_EDITOR System Customization Variable (SCV) specifies, if defined. If the GEM_EDITOR SCV is not defined, IAF invokes the designated default editor for your operating system. For details regarding the default editor for your operating system, refer to the IAF guide that applies to your operating system.

Language Statements IAF 8.0 DML

6-183

FILES

If you are editing more than one file, exiting the editor for one file causes IAF to load the next file into the editor, if there is one, or to exit the FILES statement if there are no additional files to edit.

6-184

Language Statements IAF 8.0 DML

FILES

/PORT_ONLY

This qualifier causes IAF to output the specified file(s) to the terminal device.
/PRINT_ONLY[=DELETE]

This qualifier causes IAF to automatically send the contents of the specified file(s) to the default print queue. Specifying the DELETE keyword causes IAF to delete each file after printing it.
File Operation Details

The following operational qualifiers are valid only with certain file operation qualifiers (see this sections File Operation heading).
/BATCH

This qualifier is valid for use only if the FILES statement also includes the /COMPILE_ONLY or /DELETE_ONLY qualifier. The /BATCH qualifier specifies that IAF is to perform the given operation (i.e. compilation or deletion) in a batch job.
/COPIES=copies

This qualifier is valid for use only if the FILES statement also includes the /PRINT_ONLY qualifier. The /COPIES qualifier specifies the number of copies that IAF is to print for each file.
/FORM_TYPE=form_type

This qualifier is valid for use only if the FILES statement also includes the /PRINT_ONLY qualifier. The /FORM_TYPE qualifier specifies the type of form on which IAF is to print the specified file(s). For details regarding forms that are available for use at your location, refer to your System Manager.
/LOG=log_file_name

This qualifier is valid for use only if the FILES statement also includes the /COMPILE_ONLY qualifier. The /LOG qualifier specifies the log file to which IAF is to write any errors that occur during the compilation process.
/QUEUE=queue_name

Language Statements IAF 8.0 DML

6-185

FILES

This qualifier is valid for use only if the FILES statement also includes the /BATCH and /PRINT_ONLY qualifiers. The /QUEUE qualifier specifies the print queue to which IAF is to print the specified file(s).
Menu Option Display

The following qualifiers enable you to prevent one or more menu options from appearing on the File Processing menu or the Program Processing menu that IAF displays after a file has been selected from the selectable file list. IAF displays the appropriate processing menu (i.e. file or program) only if the FILES statement does not include the /NOQUERY qualifier or any file operation qualifiers (see this sections File Operation heading).
/NOCOMPILE

This qualifier causes IAF to omit the COMPILE option from the Program Processing menu.
/NODISPLAY

This qualifier causes IAF to omit the DISPLAY option from the File Processing and Program Processing menus.
/NOEDIT

This qualifier causes IAF to omit the EDIT option from the File Processing and Program Processing menus.
/NOPERFORM

This qualifier causes IAF to omit the PERFORM option from the Program Processing menu.
/NOPORT

This qualifier causes IAF to omit the PORT option from the File Processing and Program Processing menus.
/NOPRINT

This qualifier causes IAF to omit the PRINT option from the File Processing and Program Processing menus. /NOREDRAW

6-186

Language Statements IAF 8.0 DML

FILES

This qualifier causes IAF to omit the REDRAW option from the File Processing and Program Processing menus. The REDRAW option applies only if you have IAFs graphics facility installed on your system.
/NORENAME

This qualifier causes IAF to omit the RENAME option from the File Processing and Program Processing menus.

Examples
FILES/EDIT_ONLY/NOQUERY a*.dml

This example causes IAF to sequentially present for editing all files in the current default directory that have names that start with a, and .dml as their filetype.
#FILE=abc.lis FILES/PRINT_ONLY/NOQUERY/QUEUE=PRINTER1 #FILE

This example causes IAF to print the file that the #FILE variable indicates (abc.lis) to the PRINTER1 print queue.
FILES/CHECK/COMPILE_ONLY *.dml

This example causes IAF to display in a selectable file list all files in the current default directory that have .dml as their filetype. Once a file selection takes place, IAF performs the equivalent of a COMPILE/CHECK on the selected file. For details regarding the COMPILE/CHECK statement, refer to its description in this chapter.

Related Topics
The following references contain information pertaining to the FILES statement: This chapters discussion of the COMPILE statement. The discussion of the File Manager utility in the IAF System Reference Manual.

Language Statements IAF 8.0 DML

6-187

FIND IN

FIND IN
Syntax
FIND IN [stream_name:|database_handle.]table_name[/qualifiers]

Category
Data access

Description
This statement causes IAF to search for a record or set of records in a given table, and upon finding a record, to place it into the user buffer associated with the table. The FIND statement creates a record stream via which to retrieve the record(s) it finds. If the FIND statement succeeds (i.e. IAF finds a record), IAF places the record into the user buffer associated with the given table and makes the records data available for subsequent use. Additionally, IAF sets the %STATUS special variable to the value, %SUCCESS. You can then use the FETCH statement to retrieve any remaining records from the stream. If the FIND statement fails (i.e. IAF cannot locate a record), IAF sets the %STATUS special variable to the value, %FAILURE, and terminates the stream that the FIND statement created. IAF displays no error message if the FIND statement fails. When ending the record stream, IAF executes an implicit CLEAR_BUFFER statement for the table with which the stream is associated. This statement causes IAF to set all field entries in the streams user buffer to missing or null, except for any modified PID fields, which remain untouched. If the table that the FIND statement specifies is part of an implicit or explicit domain, use the CHECK_DOMAIN statement instead of the FIND statement to look-up the required record. For details regarding domains, refer to the IAF Users Guide.
stream_name

This is the name of the secondary stream that IAF is to use when executing the FIND statement. IAF uses the primary stream associated with the specified table unless the FIND statement includes a stream name parameter or a /SECONDARY qualifier (see the qualifier descriptions that follow). Note that using the specified tables primary

6-188

Language Statements IAF 8.0 DML

FIND IN

stream when executing the FIND statement causes IAF to overwrite any record that user buffer associated with the primary stream currently holds, regardless of whether the FIND statement succeeds or fails. If the FIND statement includes a stream name parameter, IAF creates a secondary stream having the given name, and uses it when executing the FIND statement. Using a secondary stream when executing the FIND statement causes any record in the user buffer associated with the specified tables primary stream to remain untouched.
database_handle

This is the handle for the database that holds the table on which the FIND statement is to operate. It is necessary to include a database handle only if you have invoked multiple databases, and the specified table does not exist in the current default database. Note that the database handle and the stream name are mutually exclusive parameters. To start a secondary stream on a database other than the current default database, use the FIND statements /SECONDARY and /STREAM_NAME qualifiers.
table_name

This is the name of the table in which the record to find resides.

Qualifiers
The following qualifiers are valid for use with the FIND statement:
/LOCK=option_keyword

This qualifier enables you to specify the type of record lock that IAF is to place on the records that the FIND statement selects. The following table

Language Statements IAF 8.0 DML

6-189

FIND IN

lists and describes the option keywords that are valid for use with the /LOCK qualifier. Option Keywords WRITE Description This keyword causes IAF to place an immediate write lock on any record that the stream selects. This lock mode is useful in applications that update each record that the stream selects. The WRITE lock mode prevents deadlock situations that normally occur when two users having read locks attempt to write to the same record. Note that because IAF does not allow updates on multiple- table views, IAF does not apply write locks to multiple-table views. This keyword causes IAF to place an immediate read lock on any records that the stream selects. IAF converts the read lock to a write lock only if the given application makes an attempt to write to a record. This keyword causes IAF to place no locks on the records that the given stream selects, thereby enabling other users to update the records. However, because other users can update the records, it is possible that the data that the stream selected may become obsolete while still in use. Therefore, to maintain referential and data integrity, do not use data from a stream for which the NONE lock mode is in place as the basis upon which to update other records in the database. You can write to a record that a stream using NONE lock mode selects as long as no other user has updated the record since its selection. If you attempt to write to a record that another user updated after you selected it, your transaction rolls back, and the update fails. In the absence of a /LOCK qualifier, the database engine determines the default locking mechanism to use for records that the given stream selects. For details regarding the default locking mechanism for a particular database engine, refer to the IAF guide that applies to that database engine.
/SECONDARY

READ

NONE

This qualifier causes IAF to create a secondary stream to use when executing the FIND statement instead of using the primary stream
6-190 Language Statements IAF 8.0 DML

FIND IN

associated with the specified table. As a result of using a secondary stream, any record in the user buffer associated with the tables primary stream remains untouched. Note that if the FIND statement includes the /SECONDARY qualifier but does not include a stream name specification, the name of the secondary stream is the same as the name of the table that the FIND statement specifies.
/STREAM_NAME=stream_name

This qualifier indicates the name of the stream that IAF is to create when executing the FIND statement. If the FIND statement also includes the /SECONDARY qualifier, the name that the /STREAM_NAME qualifier specifies applies to the secondary stream that IAF creates for the FIND statement. Otherwise, the stream name that the /STREAM_NAME qualifier specifies applies to the primary stream associated with the specified table. Note that if the FIND statement includes both a stream name parameter (see stream_name under this sections Description heading) and the /STREAM_NAME qualifier, the stream name that the /STREAM_NAME qualifier specifies overrides the stream name parameter.
/WITH=field_name=expression

This qualifier identifies the record(s) that the FIND statement is to select from the specified table. In the syntax above, expression is any valid expression or quoted literal. The FIND statement may include one or more /WITH qualifiers, or none at all. Note that IAF retrieves (i.e. places into the appropriate user buffer) only the first record of a selected set of records to which any specified /WITH qualifiers apply. IAF determines which record of the set to retrieve.

Examples
FIND IN CUSTOMERS /WITH=CUSTOMER_ID=#CUST_ID

This example causes IAF to select all CUSTOMERS table records for which the CUSTOMER_ID field contains the value that the #CUST_ID variable indicates. IAF uses the primary stream associated with the CUSTOMERS table to do this. If the selection is successful, IAF places one of the selected records into the user buffer associated with the CUSTOMERS tables primary stream.
FIND IN SALES_ORDERS /WITH=DEPARTMENT=SYS /WITH=ORDER_NUMBER=#ORDER_NUMBER

This example causes IAF to select all SALES_ORDERS table records for which the DEPARTMENT field contains the value, SYS, and the
Language Statements IAF 8.0 DML 6-191

FIND IN

ORDER_NUMBER field contains the value that the #ORDER_NUMBER variable indicates. IAF uses the primary stream associated with the SALES_ORDERS table to do this. If the selection is successful, IAF places one of the selected records into the user buffer associated with the SALES_ORDERS tables primary stream.
FIND IN ORDERS:SALES_ORDERS & /WITH=ORDER_DATE=12-MAR-1995 & /WITH=SALES_ID=#ID

This example causes IAF to select all SALES_ORDERS table records for which the ORDER_DATE field contains the value, 12-MAR-1995, and the SALES_ID field contains the value that the #ID variable indicates. IAF creates a secondary stream named ORDERS to do this. If the selection is successful, IAF places one of the selected records into the user buffer associated with the ORDERS stream, thereby leaving the contents of the user buffer associated with the SALES_ORDERS tables primary stream untouched. Based on this example, the following output block accesses the data in the user buffer associated with the secondary stream, ORDERS (assuming that the selection was successful):
OUTPUT_BLOCK ORDER_VALUE /ROW=2 /COL=3 & /SOURCE=ORDERS:SALES_ORDERS(ORDER_VALUE)

To retrieve the next record from the ORDERS stream and place it into the user buffer associated with the ORDERS stream, you would execute the FETCH statement as the following example illustrates:
FETCH ORDERS

Related Topics
The following references contain information pertaining to the FIND IN statement: This chapters discussions of the CHECK_DOMAIN, START_STREAM, and FETCH statements. The discussion of the %STATUS special variable in this manuals SPECIAL VARIABLES AND VALUE SYMBOLS chapter. The discussion of record streams and buffer management in the IAF Users Guide.

6-192

Language Statements IAF 8.0 DML

FINISH

FINISH
Syntax
FINISH handle

Category
Data Access and Client/Server environment.

Description
This statement closes a database previously invoked via the INVOKE statement, the Data Definition Editor's INVOKE option, or a GEM_DATABASE_n System Customization Variable (SCV). This statement can also be used to close an application previously opened via the OPEN_APPLICATION statement.

Parameters
handle

Specifies the handle of the database or application to close.

Examples
INVOKE FINANCE AS DB1 ... FINISH DB1 OPEN_APPLICATION "tcp,host,6065\un\pw::FINA" AS H CONNECT H ... DISCONNECT H FINISH H

Related Topics
The following references contain information pertaining to the RECEIVE_TABLE statement:

Language Statements IAF 8.0 DML

6-193

FINISH

This chapters discussion of the INVOKE statement. This chapters discussions of the RECEIVE_DATA, SEND_TABLE, SEND_DATA, SEND_MESSAGE, EXECUTE, END_EXECUTE, CONNECT, and DISCONNECT statements. The discussion of the IAF Client/Server environment in the IAF User Guide and the IAF guide that applies to your operating system The discussion of the Data Definition Editors Procedures option in the IAF System Reference Manual.

6-194

Language Statements IAF 8.0 DML

FLOW_BLOCK

FLOW_BLOCK
Syntax
FLOW_BLOCK [block name] /TARGET=data element

Description
The FLOW_BLOCK statement acts as an input for the flow nodes on the form. This block has no visible representation. When this block is executed, program flow will wait for a flow node to be selected with the mouse. The name of the block selected will be stored in the block's target.

Flow and Menu Blocks

The new /FLOW qualifier on menu blocks causes iBrowser to check for a flow node being clicked in addition to the normal menu block processing.

Syntax
/FLOW=(dml_statement)

The name of the flow node chosen will be stored in %FLOW_NODE

Language Statements IAF 8.0 DML

6-195

FLOW_CONNECTOR

FLOW_CONNECTOR
Syntax
FLOW_ CONNECTOR /required qualifiers [/optional qualifiers]

Description
The FLOW_CONNECTOR statement defines an arrow to be drawn between two nodes. This is a display-only statement.

Required Qualifiers
/FROM=string expression

With this qualifier, you specify a name of a flow node. An arrow will be drawn from the flow node specified with this qualifier to the flow node specified with the /TO qualifier.
/TO=string expression

With this qualifier, you specify the name of a flow node. An arrow will be drawn from the flow node specified with the /FROM qualifier to the node specified with this qualifier.

Optional Qualifiers
/TITLE=string expression

This defines a label for the arrow drawn between the two flow nodes.

6-196

Language Statements IAF 8.0 DML

FLOW_NODE

FLOW_NODE
Syntax
FLOW_NODE /required qualifiers [/optional qualifiers]

Description
The FLOW_NODE statement defines the node of a flow diagram. This is a display-only statement.

Required qualifiers
/NAME=string expression

This defines a name for the flow node and must be unique for all nodes on the form.
/ROW=numeric expression

This defines the row where the upper left corner of the flow node starts expressed in characters.
/COL=numeric expression

This defines the column where the upper left corner of the flow node starts express in characters.

Optional Qualifiers
/HEIGHT=numeric expression

This defines the height of the flow node expressed in characters. If not specified, 5 is assumed.
/WIDTH=numeric expression

This defines the width of the flow node expressed in characters. If not specified, 10 is assumed.
/TITLE=string expression

This defines a title for the flow node.

/DESC=string expression

This defines the description for the flow node.

Language Statements IAF 8.0 DML 6-197

FLOW_NODE

/GRAPHIC=string expression

This defines the graphic to be displayed in the flow node. Only a filename should be specified. It is assumed that the graphic file exists in iBrowser's Images directory.

6-198

Language Statements IAF 8.0 DML

GENERATE/FORMS

GENERATE/FORMS
Syntax
GENERATE/FORMS

Category
Utilities and program development

Description
This statement invokes IAFs Forms Generator, which enables you to create working DML programs (i.e. forms). Note that you must invoke a database prior to executing this statement in order for IAF to invoke the Forms Generator and display the Forms Generation master menu.

Related Topics
The following references contain information pertaining to the GENERATE/FORMS statement: This manuals discussions of the GENERATE/REPORTS, UTILITIES, and EDIT/FORMS statements. The discussion of forms in this manuals FORMS AND FORM QUALIFIERS chapter. The discussion of the Forms Generator in the IAF System Reference Manual.

Language Statements IAF 8.0 DML

6-199

GENERATE/REPORTS

GENERATE/REPORTS
Syntax
GENERATE/REPORTS

Category
Utilities and program development

Description
This statement invokes IAFs Report Generator and enables you to create working DML programs (i.e. REPORT forms). Note that you must invoke a database prior to executing this statement in order for IAF to invoke the Report Generator and display the Report Form Details window.

Related Topics
The following references contain information pertaining to the GENERATE/REPORTS statement: This chapters discussions of the GENERATE/FORMS, UTILITIES, and EDIT/REPORTS statements. The discussion of REPORT forms in this manuals FORMS AND FORM QUALIFIERS chapter. The discussion of the Report Generator in the IAF System Reference Manual.

6-200

Language Statements IAF 8.0 DML

GOTO

GOTO
Syntax
GOTO block_name

Category
Program flow

Description
This statement causes IAF to transfer program control to the specified block. IAF requires the given block to exist within the current form.
block_name

This is the name of the block to which to transfer program control in the current form.

Examples
GOTO GET_NEXT_CUSTOMER GOTO CONFIRM

Related Topics
The following reference contains information pertaining to the GOTO statement: The discussion of blocks in this manuals BLOCKS AND BLOCK QUALIFIERS chapter.

Language Statements IAF 8.0 DML

6-201

IF, ELSE_IF, ELSE, and END_IF

IF, ELSE_IF, ELSE, and END_IF

Syntax
IF (condition_expression) dml_statement

or
IF (condition_expression) dml_code END_IF

or
IF (condition_expression) dml_code ELSE dml_code END_IF

or
IF (condition_expression) dml_code ELSE_IF (condition_expression) dml_code [ ELSE_IF (condition_expression) dml_code . . . ] END_IF

or
IF (condition_expression) dml_code ELSE_IF (condition_expression) dml_code [ ELSE_IF (condition_expression) dml_code . . . ] ELSE dml_code END_IF

Category
Program flow

6-202

Language Statements IAF 8.0 DML

IF, ELSE_IF, ELSE, and END_IF

Description
These constructs enable you to test a condition expression to determine whether or not to execute a given DML statement or statements. You can use these constructs to: execute a single DML statement contingent upon a condition expression being TRUE (i.e. a simple IF). execute a group of statements contingent upon a condition expression being TRUE (i.e. a compound IF). evaluate another condition expression upon a condition expression being FALSE (i.e. an ELSE_IF). execute one or more DML statements contingent upon a condition expression being FALSE (i.e. an ELSE). You can nest IF, ELSE_IF, ELSE, and END_IF statements. However, each ELSE_IF and ELSE statement must reside within an IF/END_IF construct. The END_IF statement must appear on a line of its own. Compound IF statements can span blocks (i.e. the IF statement can be in one block and the END_IF statement can be in a subsequent block). Multiple ELSE_IF statements may be present in one IF/END_IF construct. If the IF statements condition expression is FALSE, IAF evaluates each ELSE_IF statements condition expression until it finds one that is TRUE. If IAF finds an ELSE_IF statement whose condition expression is TRUE, IAF executes the associated DML code, and then exits the IF/END_IF construct. Otherwise, IAF evaluates the ELSE statements condition expression, if present, or exits the IF/END_IF construct if no ELSE statement is present.
condition_expression

This is the expression that IAF evaluates. It must be enclosed in quotes. IAF interprets its value as TRUE or FALSE as follows: If the expression is: numeric and non-zero numeric and zero a string and begins with Y or y TRUE FALSE TRUE IAF considers the expression to be:

Language Statements IAF 8.0 DML

6-203

IF, ELSE_IF, ELSE, and END_IF

If the expression is: a string and begins with T or t anything else TRUE FALSE

IAF considers the expression to be:

Examples
IF (SALES_ORDERS(ORDER_DATE) = %TODAY) PERFORM READY_FOR_DISPATCH #TODAYS_ORDERS = #TODAYS_ORDERS + 1 ELSE PERFORM CHECK_REQUIRED_DATES #PAST_ORDERS = #PAST_ORDERS + 1 END_IF IF (#VARIABLE) PERFORM TRUE_CONDITION IF (#STATUS=A OR #STATUS=D) PERFORM CREDIT_CHECK END_IF IF (CUSTOMERS(TYPE)=A #MAX_ORDER_VAL=150000.00 #DISCOUNT=5 END_IF IF (#ROW<1) ERROR Row number is ELSE_IF (#ROW>20) ERROR Row number is ELSE_IF (#COL<1) ERROR Column number ELSE_IF (#COL>30) ERROR Column number ELSE PERFORM DISPLAY_DATA END_IF below minimum allowed above maximum allowed is below minimum allowed is above maximum allowed

Related Topics
The following references contain information pertaining to the IF, ELSE, and END_IF statements: This chapters discussions of the CASE and WHILE statements.

6-204

Language Statements IAF 8.0 DML

IMPORT

IMPORT
Syntax
IMPORT [/ARCHIVE=archive-file-specification] [/CHECK_ONLY] [/COMMIT_RATE=n] [/CSV] [/DATA] [/FAILURE=(failure-dml)] [/FROM=database-handle] [/LOG=log-file-specification] [/METADATA=metadata-list] [/METADATA_DUMP=metadata-dump-file-specification] [/NOAUDIT] [/NOCHECK_ONLY] [/NODATA] /NOLOG /NOMETADATA /NOSTATUS /STATUS /SUCCESS=(success-dml) /TABLES="wildcard-tablename, wildcard-tablename, ..." /TO=database-handle /VERBOSE

Category
Data Access.

Description
The IMPORT statement provides both the DML programmer and the system administrator with the means to import database table-field data directly from a source database to a target ("archive") database or from an intermediate export archive file. If the export archive file contains

Language Statements IAF 8.0 DML

6-205

IMPORT

metadata, then datatype, global field, table-field, table and index metadata referenced by table-fields in the selected tables may also be imported at the same time the table-field data is imported. Whether or not an export archive file contains metadata is determined at the time it is exported. When the IMPORT statement is executed with no qualifiers, an interactive dialog is presented. See also the closely related EXPORT statement.

Implicit Actions
An import log file is always produced. Use the /LOG qualifier to control where and under what filename the log file is produced. When no qualifiers are specified, the IMPORT statement brings up an interactive dialog containing various input fields for the user to fill in. The user may use the LIST-OF-VALUES key when prompted for the export archive file to import from. This brings up a list of all *.gem_export files in your default or working directory. You may also use the LIST-OFVALUES key when prompted for the list of export archive file tables to be imported.

Special Considerations
When metadata is copied from a source database to a target database, only that metadata which does not already exist in the target database is copied. When the /METADATA qualifier is used without any qualifier value or when MINIMUM is selected at the metadata prompt in the interactive dialog, only data-type, global-field, table-field, table, and index metadata are copied; only those global fields referenced by table-fields contained in the selected tables are copied; only data-types referenced by global-fields referenced by table-fields contained in the selected tables are copied; and only indices for the selected tables are copied. Note that since EXPORT permits you the freedom to select individual metadata objects to be exported, and import permits you the freedom to select individual metadata objects to be imported, it is possible to export or import less metadata than will actually be required during an import process when the target database during the import processing is missing required metadata. For instance, if you export only ROLE_USERS, but not ROLES during the export process (or import only ROLE_USERS during the import process), it is possible for the target database to not contain the roles that are referenced by the imported ROLE_USERS (because theyre not already in the database for whatever reason and you either did not export them or you did not import them). In this case, the
6-206 Language Statements IAF 8.0 DML

IMPORT

importation of one or more ROLE_USERS will fail. If you choose to export or import less than ALL metadata, you must understand which metadata depends upon other metadata. When you export and import ALL metadata, the metadata is both available to be imported when needed and is imported in the proper order to satisfy such metadata dependencies. When both metadata and data are copied from a source database to a target database, if any of the metadata which EXPORT attempts to add to the target database already exists, then an intermediate cross-check phase occurs. During this phase each table in the target database is checked to ensure that: The tables that are imported in the table-field data import phase are the intersection of the selected source tables and the correspondingly present target database tables. If a selected source table is not present in the target database, its table-field data is not imported. Warning messages are logged to the log file for each selected source table that is not present in the target database and for each target table that is not present in the source database or export archive file. The table-fields that are imported in the table-field data import phase are the intersection of the table-fields present in the selected source tables and corresponding target database tables. Of the tables that are to be imported in the table-field data import phase, both source and target tables must have at least one same named table-field in common. A warning message is logged to the log file for each source table that does not have at least one tablefield in common with its corresponding target database table (and then no table-field data for the tables in question is subsequently imported). All PID table-fields in each target database table to be imported must be present in the corresponding table within the source database or export archive file. An error message is logged to the log file for each missing PID table-field. These are fatal errors that cause the import to fail at the end of the metadata cross check phase. A warning message is logged to the log file for each table-field in the target database that is computed or read-only if the corresponding table-field in the source database or export archive file is NOT also computed or read-only. Table-field data for computed and read-only target database table-fields is not and cannot be imported. If both source and target are computed or readonly, then they are silently ignored.

Language Statements IAF 8.0 DML

6-207

IMPORT

The native data type category and scale of each source table-field to be imported in the table-field copy phase must match that of the same named target table-field. An error message is logged to the log file for each mismatch. Data type category and scale mismatches are fatal errors that cause the import to fail at the end of the metadata cross check phase. For the purposes of importing table-field data, GEM_ARCHIVE_FLAG and GEM_TRANSACTION_ID tablefields are not read-only. The contents of GEM_ARCHIVE_FLAG and GEM_TRANSACTION_ID table-fields are copied from source to target as-is without modification. In particular, the transaction identifiers will be those from the source table and not be reset to newly generated values when the target row is updated in place or added to the target table. This permits EXPORT / IMPORT to be used to create an archival copy of a database (which is its primary intended purpose). Note: IAF V7.0 required the source and target database tables to have the same number of table-fields. This is no longer a requirement. The cross-check phase also occurs when only data is copied from a source database to a target database. In this case the "cross-check" phase occurs before the table-field data is copied. Both the source and target databases may have been invoked using any database engine supported by IAF, including engine SERVER. When source and target engine types differ, incompatible metadata attributes are automatically dropped on a best-effort basis. The most common such attributes are Oracle table-spaces. An Oracle table-space will be dropped when both the source and target databases are Oracle databases and the target database does not contain the specified tablespace. When copying metadata to an RMS database, all newly created tables are created as DYNAMIC tables.

Qualifiers
You can append the following qualifiers to the IMPORT statement: /ARCHIVE=archive-file-specification This qualifier indicates that IAF is to import from an export archive file with the specified filename. The default file type for IAF export archive
6-208 Language Statements IAF 8.0 DML

IMPORT

files is ".gem_export." The archive qualifier value may be a quoted string literal, variable, special variable, table-field, function or an expression. The /ARCHIVE qualifier is incompatible with the /FROM qualifier. /CHECK_ONLY This qualifier indicates that the integrity of the specified export archive file is to be checked and that no other import processing is to occur. In order for the integrity check to succeed, the /SIGN qualifier must have been specified when the export archive file was produced. This qualifier is incompatible with all other qualifiers except the /ARCHIVE qualifier. /COMMIT_RATE=numeric-expression This qualifier indicates the number of records that IAF is to process before committing the current transaction. The numeric expression's value must be an integer greater than zero. IAF commits any records that are not an integral number of the commit rate when the record stream is exhausted. For example, if a given record stream retrieves 14 records and the commit rate that this qualifier specifies is 5, IAF commits a set of five records with the first transaction, a set of five records with the second transaction, and a set of four records with the subsequent transaction. Note that the commit rate is applied on a per-table basis. A commit also occurs after all records have been fetched from each table, regardless of the commit rate value. /CSV This optional qualifier indicates that a comma separated variable (CSV) text file is to be imported. When the CSV qualifier is used, the syntax and functionality of the IMPORT statement changes significantly. Please refer to the description of the IMPORT/CSV statement for details. /DATA This qualifier indicates that table-field data is to be imported from the specified source database or export archive file. By default, no table-field data is imported. /FAILURE=(failure-dml) This qualifier enables you to specify a DML statement that IAF is to execute if the import fails. For a list of DML statements that the /FAILURE qualifier can specify, refer to this manual's EXECUTING DML STATEMENTS VIA QUALIFIERS appendix.

Language Statements IAF 8.0 DML

6-209

IMPORT

/FROM=database-handle /LOG=log-file-specification Example

/LOG=sys$manager:my_database_import.log

This qualifier indicates that IMPORT is to produce a log file with the specified filename. Log-file-specification may be a quoted string literal, variable, special variable, table-field, function or an expression. The default file specification for IMPORT log files is "gem_import.log." The default for IMPORT is to create a log file. Use the /NOLOG qualifier to suppress the creation of the log file. /METADATA=metadata-list Example
/METADATA=ALL

This optional qualifier indicates that IAF metadata should be imported. If the /METADATA qualifier is used alone without any qualifier value, then only data-type, global field, index, table and table-field metadata objects are imported from the specified tables. Metadata-list can be a quoted literal, a variable, a function, a table-field or an expression in parentheses. When metadata-list is specified, it contains a comma separated list of metadata objects that are to be imported. The metadata object names that can be specified are as follows: ALL, CLASSES, DATATYPES, DOMAINS, FACILITIES, FACILITY_LINKS, FACILITY_ROLES, FIELDS, INDICES, MENU_TAGS, MESSAGES, PARAMETERS, PROCEDURES, ROLE_ADMINS, ROLE_MANAGER, ROLE_USERS, ROLES, TABLES, TIME_TRIGGERS, TRIGGERS, VIEWS. ALL indicates that all metadata objects are to be imported. Each metadata object name may also be prefixed with NO (for example, NOCLASSES) to indicate a metadata object that is not to be imported. Metadata object names are processed in the order specified. To import all except a subset of metadata objects specify ALL followed by each of the objects that are to be excluded prefixed with NO (for example, ALL,NOROLES,NOROLE_ADMINS,NOROLE_USERS). /METADATA= NOALL is the same as omitting the /METADATA qualifier altogether. /METADATA_DUMP=metadata-dump-file-specification This qualifier indicates that a metadata dump file is to be produced from the metadata contained in the export archive file. In order for the metadata dump process to succeed, the /METADATA qualifier must have been
6-210 Language Statements IAF 8.0 DML

IMPORT

specified when the export archive file was produced. The default file specification for the metadata dump file is "gem_meta_dump.gem." The metadata dump qualifier value may be a quoted string literal, variable, special variable, table-field, function or an expression. This qualifier is incompatible with all other qualifiers except the /ARCHIVE qualifier. /NOAUDIT This qualifier causes both metadata auditing and table-field data auditing to be temporarily disabled during the import. This can dramatically speed up the import process. /NODATA This qualifier indicates that table-field data is not to be imported from the specified tables in the source database or export archive file. This is the default. /NOLOG This qualifier indicates that IMPORT does not produce a log file. The default action for IMPORT create a log file. Use this qualifier to suppress the creation of a log file. /NOMETADATA This qualifier indicates that metadata is not to be imported from the specified tables in the source database or export archive file. This is the default. /NOSTATUS This qualifier indicates that IAF is not to display a status window. /STATUS This qualifier indicates that IAF is to display a status window across the screen during each phase of the import processing. A second status window is also displayed as each table is processed if the given tables processing phase exceeds 10 seconds. However, the second status window does not display during the tables record selection phase, regardless of the duration of the record selection phase. /SUCCESS=(success_dml)

Language Statements IAF 8.0 DML

6-211

IMPORT

This qualifier enables you to specify a DML statement that IAF is to execute if the import succeeds. For a list of DML statements that the /SUCCESS qualifier can specify, refer to this manual's EXECUTING DML STATEMENTS VIA QUALIFIERS appendix. /TABLES="wildcard-tablename, wildcard-tablename, ..." This qualifier indicates the database tables that are to be imported. This is a comma-separated list of wildcard table names. The "*" and "%" wildcard characters may be used within each table name to indicate a set of tables matching a wildcard pattern. ." The tables qualifier value may be a quoted string literal, variable, special variable, table-field, function or an expression. /TO=database_handle /VERBOSE This optional qualifier causes IMPORT to keep the user informed of the progress of the import operation in verbose detail. For instance, rather than just informing the user that it is exporting an entire set of metadata objects (such as tables), IMPORT will inform the user each and every time it imports an individual metadata object (such as a particular table).

Exit Status
The IMPORT statement exits with %SUCCESS when the import process succeeds and %FAILURE when it fails. You may use the /SUCCESS and /FAILURE qualifiers to "trap" these exits or you may explicitly check the value of the %STATUS variable.

6-212

Language Statements IAF 8.0 DML

IMPORT/CSV

IMPORT/CSV
Syntax
IMPORT/CSV [/CHARACTER_SET=character-set] [/DOUBLE_QUOTE] [/ESCAPE_CHARACTER=escape-character] [/FAILURE=(dml-statement)] [/FIELD_SEPARATOR=field-separator] [/FIELDS=field-list] [/FROM=CSV-file-specification] [/LOG=log-file-specification] [/METADATA=metadata-list] [/QUOTE_CHARACTER=quote-character] [/STATUS] [/SUCCESS=(dml-statement)] [/TO= database-handle.table-name]

Category
Data Access.

Description
The IMPORT/CSV statement is used to import the contents of a comma separator variable (CSV) text file into a single table. Also see the description of the EXPORT/CSV statement.

Implicit Actions
When no qualifiers (other than /CSV) are specified, the IMPORT/CSV statement brings up an interactive dialog containing various input fields for the user to fill in. The user may use the LIST-OF-VALUES key when prompted for the table to be imported, the table-fields to be imported, and the CSV file to import. If the reply to the Metadata YES/NO prompt is NO, then by default, all table-fields are selected to be imported. If the reply is YES, then by default only those table-fields listed in table-field list contained in the first row of the CSV file are selected to be imported.
Language Statements IAF 8.0 DML 6-213

IMPORT/CSV

The user must delete those table-fields that are not to be imported from the list presented. Wildcard table-field names may be entered. A blank entry for the escape character or the quote character means no escape character and no quote character respectively. Both single characters and decimal character code values may be entered for the escape character, the field separator character and the quote character.

Qualifiers
/CHARACTER_SET=character-set Example
/CHARACTER_SET=UTF-8

This optional qualifier indicates the character-set with which the CSV file was originally written. Character-set can be a quoted literal, a variable, a function, a table-field or an expression in parentheses. When this qualifier is used, IMPORT/CSV converts the contents of the CSV file from the character-set specified with this qualifier to the character-set specified with the GEM_CHARACTER_SET SCV. By default no character-set conversion occurs and the CSV file is expected to have been written using the character-set specified with the GEM_CHARACTER_SET SCV. /COMMIT_RATE=numeric-expression Example
/COMMIT_RATE=100

This qualifier indicates the number of records that IMPORT/CSV is to process before committing the current transaction. The numeric expression's value must be an integer greater than zero. IMPORT/CSV commits any records that are not an integral number of the commit rate when the record stream is exhausted. For example, if a given record stream retrieves 14 records and the commit rate that this qualifier specifies is 5, IMPORT/CSV commits a set of five records with the first transaction, a set of five records with the second transaction, and a set of four records with the subsequent transaction. A commit also occurs after all records in the table have been added or updated, regardless of the commit rate value.

6-214

Language Statements IAF 8.0 DML

IMPORT/CSV

/CSV This qualifier is required. It indicates that a comma separated variable (CSV) text file is to be read. If this qualifier is not specified, the syntax and functionality of the IMPORT statement changes significantly. Please refer to the description of the regular IMPORT statement for details. /DOUBLE_QUOTE This optional qualifier when specified causes all doubled quote characters contained within the field data in the CSV file to be replaced with single quote characters. /ESCAPE_CHARACTER=escape-character Example
/ESCAPE_CHARACTER=/

This optional qualifier specifies the character that is used to escape the field separator character when it appears within field data. Escapecharacter can be a quoted literal, a variable, a function, a table-field or an expression in parentheses. Either a single one byte character may be specified or a two or more byte decimal character code may be specified. When specifying a decimal character code rather than the actual character, if the decimal character code is less than 10, prefix it with zeros. For instance, specify 008 instead of 8. Only decimal character codes 001 through 255 are valid. The most often used escape character is the forward slash (/) character. The escape character is only used when the field data is not quoted. The default if the /ESCAPE_CHARACTER qualifier is not used is no escape character. /ESCAPE_CHARACTER= (null string; explicit no escape character) is the same as no escape character. /FAILURE=(dml-statement) Example
/FAILURE=(GOTO IMPORT_FAILED)

This optional qualifier specifies a DML statement that IAF is to execute after the IMPORT/CSV operation fails for any reason. For a list of DML statements that the /FAILURE qualifier can execute, please refer to Appendix B, Executing DML Statements Via Qualifiers.

Language Statements IAF 8.0 DML

6-215

IMPORT/CSV

/FIELD_SEPARATOR=field-separator Example
/FIELD_SEPARATOR=,

This optional qualifier specifies the character that is used to separate fields within each row in the CSV file. Field-separator can be a quoted literal, a variable, a function, a table-field or an expression in parentheses. Either a single one byte character may be specified or a two or more byte decimal character code may be specified. When specifying a decimal character code rather than the actual character, if the decimal character code is less than 10, prefix it with zeros. For instance, specify 008 instead of 8. Only decimal character codes 001 through 255 are valid. The most often used field separator character is the comma (,) character. The default if the /FIELD_SEPARATOR qualifier is not used is to use a comma , character. Because a field separator character is mandatory, /FIELD_SEPARATOR= (null string; explicit no field separator character) is not permitted. /FIELDS=field-list Example
/FIELDS=MEMBERS,USERS,RENT*,UNIT_%%%_MEASURE,A*B*C

This optional qualifier specifies a comma separated list of table-fields to be imported. Fields can be a quoted literal, a variable, a function, a tablefield or an expression in parentheses. The * and % wildcard characters may be used. By default, either the table-fields read from the first row in the CSV file are imported (when /METADATA is specified) or all table-fields in the table are imported (when /METADATA is not specified). If both /FIELDS and /METADATA are specified, then the table-field names from the first row in the CSV file are read and discarded, and the table-field names from the /FIELDS qualifier are used instead. /FROM=CSV-file-specification Example
/FROM=movies.csv

This optional qualifier specifies the file specification of the CSV file to be read. CSV-file-specification can be a quoted literal, a variable, a function, a table-field or an expression in parentheses. The default CSV file specification is the name of the table in lowercase plus a file-type of .csv.

6-216

Language Statements IAF 8.0 DML

IMPORT/CSV

/LOG=log-file-specification Example
/LOG=sys$manager:my_database_import.log

This qualifier indicates that IMPORT/CSV is to produce a log file with the specified filename. Log-file-specification may be a quoted string literal, variable, special variable, table-field, function or an expression. The default file specification for IMPORT/CSV log files is "gem_import.log." The default for IMPORT/CSV is not to create a log file. Use this qualifier if you would like a log file created. /METADATA This optional qualifier specifies that the list of table-fields to be imported is to be read from the first row of the CSV file as a field-separator character separated list. It is also permissible for the table-field names in the first row of the CSV file to be quoted with the quote character. /NOLOG This qualifier indicates that IMPORT/CSV is not to produce a log file. This is the default action for IMPORT/CSV. /NOMETADATA This optional qualifier specifies that the list of table-fields to be imported is not to be read from the first row of the CSV file. This is the default. /NOSTATUS This optional qualifier indicates that IMPORT/CSV is not to display a status window as the table rows are read from the CSV file. This is the default. /QUOTE_CHARACTER=quote-character Example
/QUOTE_CHARACTER=

This optional qualifier specifies the character that is used to quote fields in CSV file. Quote-character can be a quoted literal, a variable, a function, a table-field or an expression in parentheses. Either a single one byte character may be specified or a two or more byte decimal character code may be specified. When specifying a decimal character code rather than the actual character, if the decimal character code is less than 10, prefix it

Language Statements IAF 8.0 DML

6-217

IMPORT/CSV

with zeros. For instance, specify 008 instead of 8. Only decimal character codes 001 through 255 are valid. The most often used quote character is the double-quote () character. The default quote character if the /QUOTE_CHARACTER qualifier is not used is the double quote character. Specify /QUOTE_CHARACTER= (null string; explicit no quote character) to indicate that quoting is not to be expected and not to be handled. /STATUS This optional qualifier indicates that IMPORT/CSV is to display a status window across the screen as the table rows are read from the CSV file. /SUCCESS=(success-dml) Example
/SUCCESS=(GOTO EXPORT_SUCCEEDED)

This optional qualifier specifies the DML statement that IAF is to execute if the IMPORT fails for any reason. For a list of DML statements that the /SUCCESS qualifier can execute, please refer to Appendix B, Executing DML Statements Via Qualifiers. /TO=[database-handle.]table-name Example
/TO=FIN.UNITS_OF_MEASURE

This required qualifier specifies the name of the table to be imported. The qualifier value can be an unquoted literal (as shown above in the example), a quoted literal, a variable, a function, a table-field or an expression in parentheses. This is a required qualifier. The databasehandle. portion is optional and defaults to the database-handle of the default database.

Exit Status
After the IMPORT/CSV statement executes, the special variable %STATUS is set to one of the following values: %SUCCESS if the import succeeded. %FAILURE if the import failed.

6-218

Language Statements IAF 8.0 DML

IMPORT/CSV

%EXIT if IMPORT/CSV was specified with no other qualifiers, an interactive dialog with the user occurred, and the user hit the GM_EXIT key. %BACK if IMPORT/CSV was specified with no other qualifiers, an interactive dialog with the user occurred, and the user hit the GM_BACK key at the first prompt.

Language Statements IAF 8.0 DML

6-219

IMPORT/XML

IMPORT/XML
Syntax
IMPORT/XML & [/CREATE] & [/CREATE_IF] & [/ERROR_TEXT=error-text] & [/REPLACE] & [/RESULTNAME=resultname] & /SOURCE=source & [/TABLE=table-name] & [/TO=database-tag]

Description
This statement imports a single table from a Microsoft ADO.net XML data table format data stream to a table in a database.

Qualifiers
The following qualifiers are valid for use with the IMPORT/XML statement. /CREATE This qualifier causes a non-persistent virtual table to be created on-the-fly. Any existing non-persistent virtual table by the same name is deleted before the new virtual table is created. An error occurs if the table already exists and the existing table is not a non-persistent virtual table. Tablefield names in the newly created virtual table are taken from the XML data stream. All table-fields in the newly created virtual table are given datatype TEXT with lowercase permitted and are made just long enough to contain the longest data element for each table-field as found in the XML data stream.

6-220

Language Statements IAF 8.0 DML

IMPORT/XML

/CREATE_IF This qualifier is nearly the same as the /CREATE qualifier with the difference being that a virtual table is only created if a table by the same name does not already exist. If a table by the same name already exists, then the existing table is used as-is. /CREATE and /CREATE_IF are mutually exclusive. Specify one or the other, but not both. /ERROR_TEXT This qualifier specifies where to place any error message text produced by the import process. /REPLACE This qualifier causes any existing data present in an already existing table to be deleted before the XML data stream is imported. This qualifier has no effect if the table is created on-the-fly (it is already empty). Use this qualifier with caution! /RESULTNAME This qualifier specifies where to place the table name of the table that was effectively imported. DML programs can use this qualifier to determine the name of the table that is actually imported when /TABLE is not specified and the XML data stream is permitted to specify the table name. /SOURCE This qualifier specifies where to obtain the XML data stream to import. For example, a text string variable. /TABLE This qualifier specifies the table to import to. This overrides any table name present in the XML data stream. If /TABLE is not specified, then the table name is taken from the XML data stream. Note that the specified table doesnt have to be a virtual table. /TO This qualifier specifies the database tag name of the database to import to. This overrides any database tag prefix present on the table name in the XML data stream. (The table name in the XML data stream can be in the format database-tag.table-name.) If a database tag name is not specified, then the database tag name is taken from the database tag name

Language Statements IAF 8.0 DML

6-221

IMPORT/XML

prefix on the table name in the XML data stream. If the table name in the XML data stream does not have a database tag prefix, then the default database is used.

Related Topics
See also the EXPORT/XML statement.

6-222

Language Statements IAF 8.0 DML

INVOKE

INVOKE
Syntax
INVOKE database_spec AS database_handle [/qualifiers]

Category
Data access

Description
This statement dynamically opens a local database or connects to a Database Server to access a remote database. The syntax that you use for the INVOKE statement determines the statements behavior. To use the INVOKE statement to connect to a Database Server, you must either append the /ENGINE=SERVER qualifier to the INVOKE statement or set the GEM_DEFAULT_ENGINE System Customization Variable (SCV) to SERVER prior to executing the INVOKE statement. Additionally, the given database specification (database_spec) must include specific Client/Server components as outlined in this sections description of the INVOKE statements database specification parameter. In IAF, the concept of a default database exists. This is the database on which all operations take place unless you explicitly specify otherwise. IAF determines the default database as follows: The default database is the one that the SET DATABASE statement specifies. If you do not use the SET DATABASE statement to specify the default database, the default database is the one to which you set the GEM_DATABASE_1 System Customization Variable (SCV). If you do not use the SET DATABASE statement or the GEM_DATABASE_1 SCV to specify the default database, the default database is the first database that you invoke via the INVOKE statement or INVOKE option.
database_spec

This specifies the database that IAF is to invoke. When using the INVOKE statement to invoke a local database, the database engine in use determines the exact format that this syntax component is to have. For details regarding the format to use for the database specification when
Language Statements IAF 8.0 DML 6-223

INVOKE

invoking a local database, refer to the IAF guide that applies to the database engine in use. When using the INVOKE statement to connect to a Database Server to access a remote database, the database specification is to have the following syntax:
node_name\username\password::application_name:database_name

The following table lists and describes the components of this syntax. Component node_name username password Description This is the name of the node on which the IAF Server to use is running. This is a valid username for an account on the system on which the IAF Server to use is running. This is the password for the given username. Specifying * as the password causes IAF to display a window at run-time, prompting for the password, and also allowing entry of a new node name and username. Subsequent connections (accomplished via the INVOKE or CONNECT statement, or a GEM_DATABASE_n SCV) specifying the same node and Server Application do not cause IAF to display the window. This is the name of the IAF Server Application to use (i.e. the name specified in the Server start-up resource file via the APPLICATION resource). For details regarding Server start-up resource files, refer to the discussion of IAFs Client/Server Environment in the IAF Users Guide. This is the name of the database that IAF is to invoke at start-up time (the name specified in the Server start-up resource file via the DATABASE resource). For example, if the resource file contains the following entry: DATABASE=INV=INVENTORY the database_name syntax component would be INV. For details regarding Server start-up resource files, refer to the discussion of IAFs Client/Server Environment in the IAF Users Guide.
database_handle

application_nam e

database_name

This is the unique name via which to reference the database within IAF.
6-224 Language Statements IAF 8.0 DML

INVOKE

Qualifiers
The following qualifiers are valid for use with the INVOKE statement:
/NOIMPLICIT

This qualifier disables IAFs default validation of implicit domains that exist between two tables. For details regarding domains, refer to the IAF Users Guide.
/ENGINE=engine_type_keyword

This qualifier allows you to specify an engine type keyword that indicates the database engine associated with the database upon which the INVOKE statement is to operate. If the INVOKE statement does not include this qualifier, the default engine type is the one that the GEM_DEFAULT_ENGINE SCV specifies. If the GEM_DEFAULT_ENGINE SCV is not defined, the default engine type depends upon the operating system on which you are currently running. For details regarding the GEM_DEFAULT_ENGINE SCV and the default database engine type for a particular operating system that IAF supports, refer to the IAF guide that applies to that operating system. Following are the engine type keywords that are valid for use with this qualifier:
SERVERRDBMSSQLSERVER ORACLERMS

The SERVER keyword indicates that the INVOKE statement is to connect to the indicated Database Server and invoke the given database.

Examples:
INVOKE FINANCE AS FIN /ENGINE=RDB

This example invokes the local database, FINANCE, using the Rdb database engine, and assigns the database handle, FIN, to the database.
INVOKE SABER\LYNNE\*::APP1:PARTS_SALES AS PS /ENGINE=SERVER

This example causes IAF to display a window prompting the end user to enter a password, and allowing the end user to enter a node name and username other than SABER and LYNNE, respectively. If the end user enters valid login access control information, IAF connects the Client to the Server Application named APP1 on the specified node, invokes the PARTS_SALES database, and assigns the handle, PS, to it.

Language Statements IAF 8.0 DML

6-225

INVOKE

Metadata Batching
When a database is invoked, IAF checks to see if a partially processed metadata batch update exists. Metadata batch update is a feature (controlled by START_METADATA_BATCH and END_METADATA_BATCH commands) which accumulates a set of metadata changes to apply them in an efficient manner. The pending updates are stored in an internal IAF metadata table. If a failure occurred during the metadata update portion of a metadata batch update, the database is in an inconsistent state until the batch update is completed. If IAF detects a partially processed metadata update, then the invoke will fail with a message indicating that a metadata batch update is in progress (GSR-E-HAVE_METABATCH). If those updates are being carried out in another session, wait for them to complete and retry the invoke. If a batched update fails during its execution, then system logs and the IAF log file should be checked to determine the cause of the failure and appropriate remedial action taken. (For example, system parameters may have to increase to allow the metadata update to proceed.) Once the issue that caused the metadata batch failure is resolved, the database must be invoked with either the /RESUME_METADATA_BATCH or /FLUSH_METADATA_BATCH qualifier to complete or terminate the metadata batch update. Only then can the database be invoked successfully without the GSR-EHAVE_METABATCH error being generated. Attempts to circumvent these procedures can result in the database metadata being left in a compromised state.
/RESUME_METADATA_BATCH

This qualifier will cause any partially executed metadata update batch to be completed when the database is invoked. The problem causing the original failure of the metadata batch must have been resolved before this qualifier can be used to successfully complete the metadata updates.

/FLUSH_METADATA_BATCH

This qualifier for the INVOKE command will cause any partially executed metadata update batch to be flushed (i.e. deleted) when the database is invoked. Flushing the batch essentially consists of deleting all the entries from the internal IAF table where they are stored. It is intended as a last resort when the batch cannot be restarted. If the batch was only partially

6-226

Language Statements IAF 8.0 DML

INVOKE

executed, it will be necessary to manually fix the metadata in the database (e.g. using SQL).

Migrating to IAF 6.1

In prior versions of IAF, when a database was invoked IAF would automatically upgrade the IAF internal metadata tables to the current structure level. With this version of IAF is a database needs upgrading, the upgrade must be done manually. All attempts to INVOKE the database will fail with a:
%GSR-E-UPGRADE, database not at current metadata level; upgrade required

message. To upgrade a database to the current metadata structure level, you must INVOKE it with the /UPGRADE qualifier.

Example:
GEM> INVOKE database AS handle /ENGINE=engine /UPGRADE

If you use compiled metadata for a database, be sure to recompile the metadata after upgrading the database. It is always a good idea to invoke the database as super user. Most customers dont give enough database permissions to the user invoking IAF database. For example, for ORACLE set GEM_DATABASE_1 to:
sys\password\finance

Where password is the password for the ORACLE super user sys. You should invoke each of the individual databases one at a time. You should unset GEM_DATABASE_2 and set:
GEM_DATABASE_1=sys\password\finance

When you invoke IAF, it will automatically perform the upgrade on finance database, then sets GEM_DATABASE_1 to the value previously assigned to GEM_DATABASE_2. Setting:
GEM_DATABASE_1=sys\password\manufacturing

and invoking IAF automatically performs the upgrade on manufacturing database. Ensure that there are no indexes created on GEM_PRIVILEGES table before perfoming the upgrade. This must be checked for each of the databases being upgraded.

Language Statements IAF 8.0 DML

6-227

INVOKE

The Security Setup windows access control list will not contain an entry for the operating system account of the database creator. This is because existing databases do not store the operating system account username of the user who creates a given database. IAF grants the operating system super user account (i.e. root on UNIX systems, and SYSTEM on OpenVMS systems) all access privileges to the database. However, the root or SYSTEM username does not display in the Security Setup windows access control list. The operating system super users access privileges are hard coded within IAF. On UNIX systems, the super user is a user with UID 0. On OpenVMS systems, the super user is a user with CMKRNL privilege. During the upgrade procedure, the IAF super user account assigns the EXECUTE privilege to the special group, PUBLIC, for any existing facility that has not explicitly received one or more access privileges (i.e. an entry for the special group PUBLIC with EXECUTE privilege granted by IAF will display in the Facility User Access Options window). The System/Facility User Access Options window will not contain an entry for the username of the facility creator for any existing facilities. This is because the database does not store the operating system account username of the user who creates a given facility. During the upgrade procedure, IAF will combine multiple entries for the same username into one entry in the System/Facility User Access Options windows access control list. To illustrate, if the access control list contains the following entries for the username jim:
JIMCO JIMEX JIMMO

IAF will combine the individual entries into one entry as follows:
JIMCO+EX+MO

If you attempt to add a new entry in the System Facility User Access Options windows access control list for a username for whom an entry already exists, IAF displays the following error message:
Grantee already exists for this Facility

While performing an upgrade, if you get the IAF prompt or to the REN/CS menu, your upgrade was completed successfully. If your upgrade was not a success, you will leave IAF with a bugcheck dump.
6-228 Language Statements IAF 8.0 DML

INVOKE

To ensure that you have no problems, the following checks can be done using sqlplus (for ORACLE) or isql (for SYBASE). These checks are obviously done after performing the upgrade. Run the SQL
SELECT * FROM GEM_DATABASE

Under the column name GEM_PATCH_LEVEL a value appears. For ORACLE databases the value should be 25. If the appropriate value was returned and you didnt get a bugcheck dump, your upgrade was successful and you do not need to check anything else. Run the query
SELECT * FROM GEM_PRIVILEGES WHERE GEM_OBJECT_TYPE=6

What is returned might be a single row. If your upgrade has gone well and the above row was displayed, you do not need to do anything. If your upgrade was not complete and the above row is displayed, then delete this row by running the following SQL
DELETE FROM GEM_PRIVILEGES WHERE GEM_OBJECT_TYPE=6

Related Topics
The following references contain information pertaining to the INVOKE statement: This chapters discussions of the FINISH and SET DATABASE statements. The discussions of the INVOKE statement and INVOKE option in the IAF guide that applies to your database engine. The discussions of the GEM_DATABASE_n and GEM_DEFAULT_ENGINE SCVs in the IAF guide that applies to your operating system. The discussion of IAFs Client/Server Environment in the IAF Users Guide and the IAF guide that applies to your operating system. The discussion of domains in the IAF Users Guide.

Language Statements IAF 8.0 DML

6-229

LICENSE

LICENSE
Syntax
LICENSE

Category
Miscellaneous

Description
For administrative users, this statement brings up the Ross Systems Automated Licensing Main Menu. For non-administrative users, this statement does nothing. For the purposes of licensing, an administrative user is any user who has unrestricted write access to the directory in which license files are stored. See also the description of the GEM_LICENSE_DIALOG SCV.

6-230

Language Statements IAF 8.0 DML

LOAD

LOAD
Syntax
LOAD file_spec INTO [database_handle.]table_name(field_name)

Category
Data access

Description
This statement causes IAF to load a text file into the specified segmented string field. The data in the file can be of any type (i.e. text or binary).This means that you can store proprietary formatted data such as a word processing file, a spreadsheet, or a graphical image in the database.
file_spec

This is the file specification for the text file that IAF is to load, and can be any valid file specification, such as a quoted string or variable that contains the name of the file.
database_handle

This is the handle for the database in which the specified table exists. It is necessary to include a database handle only if you have invoked multiple databases, and the given table does not exist in the current default database.
table_name(field_name)

This is the name of the segmented string table field into which IAF is to load the text file.

Examples
CLEAR_BUFFER A LOAD filename.txt INTO a(file_name) add to a commit

Related Topics
The following reference contains information pertaining to the LOAD statement:

Language Statements IAF 8.0 DML

6-231

LOAD

This chapters discussion of the UNLOAD statement.

6-232

Language Statements IAF 8.0 DML

LOG

LOG
Syntax
LOG [/ERROR|/WARNING|/INFO|/DEBUG] "message"

Category
Miscellaneous

Description
This statement provides an easy way for DML programs to log debug or error information to a log file. The LOG statement outputs the log message to the log file if the logging level for this message is less than or equal to the requested logging level for the application (as set by SET LOG_LEVEL). The default logging level is ERROR. The log output includes: date, time, username, PID, facility, form name, filename, line number, level, message.

Example 1
LOG /DEBUG "This is a debug message" LOG /WARNING "This is a warning message"

Example 2
! Turn on debug logging SET LOG_LEVEL DEBUG . . . !Expensive operations, such as accessing information from the database, !should only be performed if the information will actually be logged. IF (%LOGGING_DEBUG) ! Get inventory count from the DB into #count. #msg = "Inventory Count is "& #count LOG /DEBUG #msg END_IF

Language Statements IAF 8.0 DML

6-233

LOG

Related Topics
The following references contain information pertaining to the LOG statement: This chapter's discussion of the SET LOG_LEVEL, SET LOG_FILE and LOG statements. The discussion of the special variables %LOGGING_ERROR, %LOGGING_WARNING, %LOGGING_INFO, %LOGGING_DEBUG and %LOG_FILE in the Special Variables and Value Symbols Chapter of this manual.

6-234

Language Statements IAF 8.0 DML

MAIL

MAIL
Syntax
MAIL /TO=to_address [/SUBJECT=subject_text] /FILE=send_file_spec

or
MAIL /TO=to_address [/SUBJECT=subject_text] /TEXT=text_line [/TEXT=text_line[...]]

Category
Inter-process communication

Description
This statement provides a portable mechanism via which an application can send electronic mail messages (as opposed to a non-portable mechanism, such as the CLI statement).

Qualifiers
The following qualifiers are valid for use with the MAIL statement:
/FILE=send_file_spec

This qualifier enables you to specify the file specification for the file that IAF is to send in the body of the mail message. Note that the /TEXT qualifier and the /FILE qualifier are mutually exclusive.
/SUBJECT=subject_text

This qualifier enables you to specify a line of text that is to appear at the subject heading of the given mail message. If the MAIL statement does not include this qualifier, no text appears at the mail messages subject heading.
/TEXT=text_line

This qualifier enables you to specify a line of message text that IAF is to include in the body of the mail message. A given MAIL statement can include multiple /TEXT qualifiers. Note that the /FILE qualifier and the /TEXT qualifier are mutually exclusive.

Language Statements IAF 8.0 DML

6-235

MAIL

/TO=to_address

This qualifier enables you to specify the address of the user to whom IAF is to send the mail message. The address that this qualifier specifies can include any specifications (i.e. username, node name, etc.) that together comprise a valid mail address for the operating system on which you are currently running.

Examples
MAIL /TO=John /SUBJECT=Tape Distribution List /FILE=tdist.dis MAIL /TO=Walter /TEXT=Processing run completed

Related Topics
The following references contain information pertaining to the MAIL statement: This chapters discussion of the CLI statement. Your operating systems mail utility documentation.

6-236

Language Statements IAF 8.0 DML

MAIL/SMTP

MAIL/SMTP
Syntax
MAIL/SMTP & [/Attachments=comma-separated-file-specification-list] [/Bcc=comma-separated-list-of-mailbox-addresses] [/Cc=comma-separated-list-of-mailbox-addresses] [/Domain=smtp-server-authentication-domain] [/Error_Code=gembase-smtp-error-code] [/Error_Text=gembase-smtp-error-text] [/File=message-body-filename] [/From=comma-separated-list-of-mailbox-addresses] [/Header=custom-header-text] [/Importance=importance-level] [/Notify=delivery-status-notification-keyword-list] [/Options=comma-separated-options-list] [/Password=smtp-server-authentication-password] [/Port=smtp-server-port] [/Reply_To=mailbox-address] [/Response_Code=smtp-server-response-code] [/Response_Text=smtp-server-response-text] [/Sender=mailbox-address] [/Sensitivity=sensitivity-level] [/Server=smtp-server-hostname] [/Subject=subject-text] [/Text=message-body-text] [/Timeout=smtp-server-response-timeout] /To=comma-separated-list-of-mailbox-addresses [/Username=smtp-server-authentication-username]

Category
Inter-process communication

Language Statements IAF 8.0 DML

6-237

MAIL/SMTP

Description
This statement provides a portable mechanism via which an application can send electronic mail messages to a mail forwarding host using the Simple Mail Transfer Protocol (SMTP). In contrast to the MAIL statement which uses platform-specific host operating system facilities to send mail, the MAIL/SMTP statement uses no host operating system facilities. Instead it relies upon your network having an SMTP mail forwarding host available to process and forward electronic mail.

Qualifiers
The following qualifiers are valid for use with the MAIL/SMTP statement:
/ATTACHMENTS=comma-separated-list-of-file-specifications

This optional qualifier specifies a comma separated list of the file specifications of files to be attached to the message. The qualifier value can be a quoted literal, a variable, a function, a table-field or an expression in parentheses.
/BCC=comma-separated-list-of-mailbox-addresses

The /BCC qualifier (where the "BCC" means "Blind Carbon Copy") specifies a comma separated list of the mailbox addresses of message recipients whose addresses are not to be revealed to other recipients of the message. In the IAF DML implementation blind copies are truly blind. When this qualifier is used, the message header contains a Bcc: header line, but it is empty and does not indicate who the blind recipients actually are, only that they exist. A completely separate copy of the message is sent to each blind recipient. Other than the empty bcc header line, the separate message sent to each blind recipient gives no indication whatsoever of whom any of the other message recipients (blind or otherwise) are or even that they exist. This is an optional qualifier. The qualifier value can be a quoted literal, a variable, a function, a table-field or an expression in parentheses.
/CC=comma-separated-list-of-mailbox-addresses

The /CC qualifier value (where the "CC" means "Carbon Copy" in the sense of making a copy on a typewriter using carbon paper) contains the mailbox addresses of others who are to receive the message, though the content of the message may not be directed at them. This is an optional qualifier. The qualifier value can be a quoted literal, a variable, a function, a table-field or an expression in parentheses.

6-238

Language Statements IAF 8.0 DML

MAIL/SMTP

/DOMAIN=smtp-client-authentication-domain

This optional qualifier specifies the domain to be used to authenticate the message sender. Some SMTP servers require authentication. The qualifier value can be a quoted literal, a variable, a function, a table-field or an expression in parentheses. A domain is required for the NTLM authentication method. The NTLM authentication method is only used when 1) the SMTP server supports NTLM authentication; 2) the SMTP server does not support a more secure authentication method and 3) you supply a domain in addition to a username and password. The default domain can be set with the GEM_SMTP_AUTH_DOMAIN SCV. If specified, this qualifier overrides the SCV setting. See also the /USERNAME and /PASSWORD qualifiers.
/ERROR_CODE=iaf-dml-smtp-error-code

This optional qualifier can be used to obtain an IAF DML SMTP facility specific error code number in the event that an error occurs during the composition or transmission of the message. Note that this is not the same as the SMTP error code as returned by the SMTP server. For the latter, please see the /RESPONSE_CODE qualifier. The qualifier value can be a variable, a table-field or any DML language construct that is also suitable as the /TARGET on an input bock.
/ERROR_TEXT=iaf-dml-smtp-error-text

This optional qualifier can be used to obtain the IAF DML SMTP facility specific error code text in the event that an error occurs during the composition or transmission of the message. Note that this is not the same as the SMTP error text as returned by the SMTP server. For the latter, please see the /RESPONSE_TEXT qualifier. The qualifier value can be a variable or a table-field or any DML language construct that is also suitable as the /TARGET on an input block.
/FILE=message-body-text-file-specification

This optional qualifier enables you to specify the file specification of a file whose content IAF DML is to send as the body of the mail message. The qualifier value can be a quoted literal, a variable, a function, a tablefield or an expression in parentheses. Note that the /TEXT qualifier and the /FILE qualifier are mutually exclusive.
/FROM=comma-separated-list-of-mailbox-addresses

The /FROM qualifier specifies a comma-separated list of one or more mailbox addresses of author(s) of the message, that is, the address(es) of the person(s) or system(s) responsible for the writing of the message. If the /FROM qualifier value contains more than one mailbox address, then
Language Statements IAF 8.0 DML 6-239

MAIL/SMTP

the /SENDER qualifier should be used and its value must contain a single mailbox address. See also the related /SENDER, /REPLY_TO and /RETURN_RECEIPT_TO qualifiers. The qualifier value can be a quoted literal, a variable, a function, a table-field or an expression in parentheses.
/HEADER=custom-header-text

This optional qualifier can be used to include custom message header. The qualifier value can be a quoted literal, a variable, a function, a tablefield or an expression in parentheses. This is a powerful qualifier in the sense that it permits you to add any sort of header line as you please to your message. It is also a dangerous qualifier in the sense that you can easily cause your message to become improperly formatted and subsequently undeliverable. In order to use this qualifier you must understand the syntax for the message header you wish to include. IAF DML will encode all non-US-ASCII characters (if any) found in your headers and wrap your headers if they exceed 76 bytes in length. These functions will be performed in conformance to the RFC 2047 MIME standard for header extensions. The /HEADER qualifier can be specified multiple times to include multiple custom headers.
/IMPORTANCE=importance-level

This optional qualifier can be used to give the recipient some indication of how important the message is. The qualifier value can be a quoted literal, a variable, a function, a table-field or an expression in parentheses. The valid importance levels are low, normal and high.
/NOTIFY=delivery-status-notification-keyword-list

This optional qualifier specifies the conditions under which the SMTP server should generate and send delivery status notification (DSN) messages to the message sender. The qualifier value can be a quoted literal, a variable, a function, a table-field or an expression in parentheses. The keyword list may contain one or more of the following keywords: SUCCESS, FAILURE, DELAY, NEVER. Delivery status notification is officially an enhanced SMTP feature. Not all SMTP servers support this feature. Even when an SMTP server supports the feature, not all mail delivery and user agents may honor the request. However, when any keyword other than NEVER is specified, IAF DML also adds the Disposition-Notification-To and Return-Receipt-To headers to the message. These headers often have the same effect and are honored by many more mail transport and user agents. If the NEVER keyword is specified, it overrides all the other keywords. NEVER requests that a delivery status notification message not be returned to the sender under any conditions. The SUCCESS and FAILURE keywords request that a

6-240

Language Statements IAF 8.0 DML

MAIL/SMTP

delivery status notification message be issued on successful delivery or delivery failure, respectively. The keyword DELAY indicates the sender's willingness to receive "delayed" delivery status notifications. Delayed delivery status notifications may be issued if delivery of a message has been delayed for an unusual amount of time (as determined by the mail transport agent at which the message is delayed), but the final delivery status (whether successful or failure) cannot be determined. Note that the delivery status notifications are sent via return mail.
/OPTIONS=comma-separated-options-list

This optional qualifier can be used to specify MAIL/SMTP command options. The qualifier value can be a quoted literal, a variable, a function, a table-field or an expression in parentheses. The following options are defined:
8BITMIME If your SMTP server supports the "8BITMIME" extension, then this option enables the use of "8bit" content transfer encoding for the message body. If your SMTP server does not support the "8BITMIME" extension, then this option is ignored. This option is disabled by default (unless enabled with the GEM_SMTP_OPTIONS SCV). 8BITMIME is disabled by default in order to prevent messages from bouncing from downstream mail transport agents that either do not support 8BITMIME or are unwilling to downgrade the message encoding when they encounter a relay host that does not support 8BITMIME. ANONYMOUS_TOKEN=token Override sending of a random alpha numeric token for the AUTH ANONYMOUS authentication method. Send the explicitly specified token instead. AUTH_GSSAPI_HOST Override the hostname portion of the service

principal name which MAIL/SMTP constructs when doing AUTH GSSAPI (Kerberos) authentication.
AUTH_GSSAPI_REALM Override the Kerberos realm portion of the

service principal name which MAIL/SMTP constructs when doing AUTH GSSAPI (Kerberos) authentication.
AUTH_GSSAPI_SERVICE Override the service name portion of the service principal name which MAIL/SMTP constructs when doing AUTH GSSAPI (Kerberos) authentication. If this SCV is not set the default service name is "smtp" as defined by both RFC standard and IANA authority. You may need to override this for non-standard service names such as those used by Microsoft Exchange Server ("SMTPSVC").

Language Statements IAF 8.0 DML

6-241

MAIL/SMTP

AUTH_GSSAPI_SPN Override the entire service principal name which MAIL/SMTP constructs when doing AUTH GSSAPI (Kerberos) authentication. This option overrides the three above. On non-Windows platforms the service principal name has the following format "service@hostname" where service is "smtp" by default and "hostname" is the fully qualified hostname of the host to which you are connecting. On Windows platforms the service principal name has the format " AUTH_NOT_PERMITTED This option specifies that MAIL/SMTP is

NOT permitted to perform authentication regardless of the presence or absence of any other qualifiers such as /USERNAME, /PASSWORD and /DOMAIN.
AUTH_NOT_PERMITTED=comma-separated-authentication-methodlist This option specifies a comma separated list of authentication

methods which MAIL/SMTP is not permitted to use.

AUTH_NOT_REQUIRED This option specifies that authentication is not required. This is the default. AUTH_PERMITTED This option specifies that MAIL/SMTP is permitted

to use any suitable SASL authentication method which both it and the server have in common. This is the default. For more information see the section on client authentication below.
AUTH_PERMITTED=comma-separated-authentication-method-list

This option not only specifies that MAIL/SMTP is permitted to perform authentication, but also specifies a comma separated list of the authentication methods which are permitted to be used. Methods not listed are not permitted.
AUTH_REQUIRED This option specifies that MAIL/SMTP is required to perform authentication. If authentication cannot be performed for any reason, then MAIL/SMTP disconnects from the server and the mail is not sent. Note that SMTP servers that do not support ESMTP also do not support authentication. Keep that in mind when using this option. AUTH_REQUIRED=method This option specifies one single

authentication method that MAIL/SMTP is required to use.

NO8BITMIME This option explicitly disables the use of "8bit" content transfer encoding for the message body regardless of whether or not your SMTP server supports the "8BITMIME" extension. If this option is specified, then a 7-bit safe content transfer encoding is used, either quoted-printable (for single-byte character sets) or base64 (for multi-byte

6-242

Language Statements IAF 8.0 DML

MAIL/SMTP

character sets). This is the default. Therefore this option is mainly useful to override any SCV setting which may indicate otherwise.
TLS_CHECK_SERVER_CERT This option causes MAIL/SMTP to

check the server certificate when using transport layer security (SSL/TLS). By default MAIL/SMTP does not check the server certificate.
TLS_NOCHECK_SERVER_CERT This option causes MAIL/SMTP to

not check the server certificate when using transport layer security (SSL/TLS). By default MAIL/SMTP does not check the server certificate therefore this option is mainly useful to override any SCV setting to the contrary.
TLS_CLIENT_CERT_FILE=filename The name of a file which contains

the client certificate in PEM format which is loaded when using transport layer security (SSL/TLS). This is better set with the associated SCV. This option is mainly useful in situations where you need to override the SCV setting.
TLS_PRIVATE_KEY_FILE=filename The name of a file which contains

your private key in PEM format which is loaded when using transport layer security (SSL/TLS). This is better set with the associated SCV. This option is mainly useful in situations where you need to override the SCV setting.
TLS_TRUST_CERT_DIR=path The directory which contains files with specially hashed names and which contain the trust certificatesin PEM format which are loaded when using transport layer security (SSL/TLS). This is better set with the associated SCV. This option is mainly useful in situations where you need to override the SCV setting. TLS_TRUST_CERT_FILE=filename The name of a file which contains the trust certificates in PEM format which are loaded when using transport layer security (SSL/TLS). This option overrides the TLS_TRUST_CERT_DIR option. This is better set with the associated SCV. This option is mainly useful in situations where you need to override the SCV setting.

The default options can be set with the GEM_SMTP_OPTIONS SCV.

/PASSWORD=smtp-client-authentication-password This optional

qualifier specifies the password to be used to authenticate the message sender. Some SMTP servers require authentication. The qualifier value can be a quoted literal, a variable, a function, a table-field or an expression in parentheses. The default password can be set with the GEM_SMTP_AUTH_PASSWORD SCV. If specified, this qualifier
Language Statements IAF 8.0 DML 6-243

MAIL/SMTP

overrides the SCV setting. See also the /DOMAIN and /USERNAME qualifiers.
/PORT=smtp-server-port This optional qualifier specifies the TCP port

number on the server host machine on which the SMTP server is to be contacted. By default IAF DML uses the "smtp" service port which is usually port 25. The qualifier value can be a quoted literal, a variable, a function, a table-field or an expression in parentheses. The default port can be set with the GEM_SMTP_SERVER_PORT SCV. If specified, this qualifier overrides the SCV setting. See also the /SERVER qualifier.
/REPLY_TO=mailbox-address This optional qualifier is used to indicate

the mailbox address to which the author of the message suggests that replies be sent. The qualifier value can be a quoted literal, a variable, a function, a table-field or an expression in parentheses.
/RESPONSE_CODE=smtp-response-code This optional qualifier can

be used to obtain the SMTP error code number in the event that the SMTP server forcefully rejects a command or sends the client a totally unexpected response. This qualifier is of post mortem value only as IAF DML will have already terminated the session in such an event. The qualifier value can be a variable, a table-field or any DML language construct that is also suitable as the /TARGET on an input bock.
/RESPONSE_TEXT=smtp-response-text This optional qualifier is

similar to the /RESPONSE_CODE qualifier above however it returns the full text of the response rather than just the error code. The qualifier value can be a variable, a table-field or any DML language construct that is also suitable as the /TARGET on an input bock.
/SENDER=mailbox-address This optional qualifier can be used to

specify the mailbox address of the agent responsible for the actual transmission of the message. For example, if a secretary sends a message on behalf of another person, the /SENDER qualifier should specify her mailbox address and the /FROM qualifier should specify the address of the actual author. If the originator of the message can be indicated by a single mailbox address and the author and transmitter are identical, the /SENDER qualifier should not be used. Otherwise, both qualifiers should be used. The qualifier value can be a quoted literal, a variable, a function, a table-field or an expression in parentheses.
/SENSITIVITY=sensitivity-level This optional qualifier can be used to give the recipient some indication of the sensitivity of the message content. The qualifier value can be a quoted literal, a variable, a function,

6-244

Language Statements IAF 8.0 DML

MAIL/SMTP

a table-field or an expression in parentheses. The valid sensitivity levels are normal, personal, private and confidential.
/SERVER=smtp-server-hostname This optional qualifier specifies the

fully qualified domain name (FQDN) of the host machine at which the SMTP server is to be contacted. The qualifier value can be a quoted literal, a variable, a function, a table-field or an expression in parentheses. The default port can also be set with the GEM_SMTP_SERVER_NAME SCV. If specified, this qualifier overrides the SCV setting. See also the /PORT qualifier.
/SUBJECT=subject-text This optional qualifier enables you to specify a

line of text that is to appear at the subject heading of the given mail message. If this qualifier is not used then no text appears at the mail message's subject heading. The qualifier value can be a quoted literal, a variable, a function, a table-field or an expression in parentheses.
/TEXT=message-body-text-line This optional qualifier specifies a

single line of text that is to be included in the body of the message. The qualifier value can be a quoted literal, a variable, a function, a table-field or an expression in parentheses. A mail statement can use multiple /TEXT qualifiers, one for each line of text in the message body. The first /TEXT qualifier contains the text of the first line of the message body, the second /TEXT qualifier contains the text of the second line of the message body and so on. This qualifier and the /FILE qualifier are mutually exclusive. You may use either one or more /TEXT qualifiers or the /FILE qualifier, but not both.
/TIMEOUT=smtp-server-response-timeout This optional qualifier

specifies the amount of time in seconds after which IAF DML should consider the SMTP server to have failed to respond to a command and to return a timeout error. The qualifier value can be a quoted literal, a variable, a function, a table-field or an expression in parentheses. The default timeout can also be set with the GEM_SMTP_SERVER_TIMEOUT SCV. If specified, this qualifier overrides the SCV setting.
/TO=comma-separated-list-of- mailbox-addresses This REQUIRED

qualifier specifies the address(es) of the primary recipient(s) of the message. The qualifier value can be a quoted literal, a variable, a function, a table-field or an expression in parentheses.
/USERNAME=smtp-server-authentication-username This optional qualifier specifies the username to be used to authenticate the message sender. Some SMTP servers require authentication. The qualifier value

Language Statements IAF 8.0 DML

6-245

MAIL/SMTP

can be a quoted literal, a variable, a function, a table-field or an expression in parentheses. The default username can be set with the GEM_SMTP_AUTH_USERNAME SCV. If specified, this qualifier overrides the SCV setting. See also the /DOMAIN and /PASSWORD qualifiers.

Examples
Mail/SMTP & /To='"Buggs" <Bbunny@toontown.ca.us>' & /Subject="Tape Distribution List" & /File="TapeAdvert.html" & /Attach="TapeIndex.xml,TapeLibrary.xml"

Mail/SMTP & /To='"Walter O'reilly" <cplradar@mash.tv>' & /Text="Processing run completed" & /Attach="Run1.log,Run2.log,Run3.log"

Client Authentication
By default MAIL/SMTP does not authenticate the client to the server. If your SMTP server requires authentication, you must use the /DOMAIN, /PASSWORD and /USERNAME qualifiers or set the GEM_SMTP_AUTH_DOMAIN, GEM_SMTP_AUTH_PASSWORD and GEM_SMTP_AUTH_USERNAME SCVs respectively. IAF DML supports several forms of SMTP client authentication: 1. 2. 3. 4. 5. 6. 7. AUTH GSSAPI AUTH NTLM AUTH CRAM-MD5 AUTH DIGEST-MD5 AUTH LOGIN AUTH PLAIN AUTH ANONYMOUS

The order of preference is as listed above and is not currently alternable. CRAM-MD5, DIGEST-MD5, LOGIN and PLAIN authentication all

6-246

Language Statements IAF 8.0 DML

MAIL/SMTP

require a username and password. NTLM authentication requires a username and a password. A domain is optional. ANONYMOUS authentication does not require anything. Instead it sends short token consisting of random alphanumeric characters which does not reveal your identity. You can set an explicit token with an option or SCV setting. For servers that support multiple authentication methods, IAF DML uses the most secure authentication method that both it and the server have in common. The order from most secure to least secure is as listed above. Note that DIGEST-MD5 and GSSAPI authenticate the server to the client in addition to authenticating the client to the server. GSSAPI uses your Kerberos login (KINIT) credentials on the OpenVMS and UNIX platforms. It uses your login credentials by default on Windows platforms, but can and will instead use the credentials you specify with the /USERNAME, /PASSWORD and /DOMAIN qualifiers (or their associated SCVs) if you specify them. If no username is specified, all methods (except anonymous, of course) use your login username by default. CRAM-MD5 is preferred over DIGEST-MD5 because the HMAC-MD5 transform used by CRAM-MD5 is considered to be more secure than the MD5 cryptographic hash used by DIGEST-MD5.

Mailbox Address Specification Format

The general format of mailbox address specifications understood by the MAIL/SMTP statement is as follows:
"display-name" <local-part@domain-part>

The display name portion is optional and may be omitted. The doublequote and angle bracket punctuation is optional, but very highly recommended as it helps the MAIL/SMTP statement to unambiguously identify the pertinent portions of the address specification. The above syntax is not meant to define an Internet standard or RFC compliant mailbox address format, only that format which is understood by and is acceptable to the MAIL/SMTP statement. This is a pragmatic issue. Use other formats at your own risk.

Message Format
IAF DML always writes MIME standard conformant messages. If your SMTP server supports the "8BITMIME" extension and the 8BITMIME option is specified (either explicitly using the /OPTIONS qualifier or implicitly with via the GEM_SMTP_OPTIONS SCV), then IAF DML uses "8bit" transfer encoding otherwise it chooses a 7-bit safe encoding in which all non-US-ASCII message text and all text containing certain specific character values or character sequences (control codes, eight bit values, et cetera) are encoded in either quoted printable or base64 encoding. Which encoding is used depends on the
Language Statements IAF 8.0 DML 6-247

MAIL/SMTP

GEM_CHARACTER_SET setting. Quoted printable is used for all single-byte character sets and base64 is used for all multi-byte character sets. Message headers are encoded using the UTF-8 character-set and the header "b" encoding method. Attachments are always base64 encoded regardless of content. Appropriate MIME headers are included with all messages. The MIME Content-Type is based on the file type. On the Windows platform registry entries in HKEY_CLASSES_ROOT are used to select an appropriate Content-Type. The character-set for the message body is based on the value of the GEM_CHARACTER_SET. However, per section 4.1.2 of RFC 2046 (using the lowest common denominator character set whenever possible), the US-ASCII character-set is used in preference to GEM_CHARACTER_SET whenever it is found that all characters in the message body are wholly contained within the USASCII character-set. If an XML file is used as the message body, then (when recognized as such) the character-set specified in the XML file (if any) is used instead.

Related System Customization Variables

The following fully DYNAMIC System Customization Variables (SCVs) affect the execution of the MAIL/SMTP sstatement. Note that when setting or getting these SCVs with the SET_GEM_SCV() and GEM_GEM_SCV() DML function, the "GEM_" prefix is not specified (for example, SET_GEM_SCV("GSSAPI_LIBRARY"). However, when setting environment variables or logical names, the prefix is specified.
GEM_GSSAPI_LIBRARY This SCV can be set to override the name of

the GSS API library that is loaded when and if needed at run-time to support AUTH GSSAPI authentication. The default name of the library is platform specific. You would only set this SCV if for whatever reason IAF DML was using the wrong library name. Although this SCV is dynamic, once the library is loaded, that's it. It is not unloaded and reloaded.
GEM_GSSAPI_LIBRARY_PATH This SCV can be set to override the

location of the GSS API library that is loaded when and if needed at runtime to support AUTH GSSAPI authentication. The default location of the library is platform specific. You would only set this SCV if for whatever reason IAF DML was using the wrong library location. Although this SCV is dynamic, once the library is loaded, that's it. It is not unloaded and re-loaded.
GEM_OPENSSL_CRYPTO_LIBRARY This SCV can be set to override the name of the OpenSSL Crypto API library that is loaded when and if needed at run-time to support usage of transport layer security (SSL/TLS AKA SMTP STARTTLS command). The default name of the library is
6-248 Language Statements IAF 8.0 DML

MAIL/SMTP

platform specific. You would only set this SCV is for whatever reason IAF DML was using the wrong library name. Although this SCV is dynamic, once the library is loaded, that's it. It is not unloaded and reloaded.
GEM_OPENSSL_SSL_LIBRARY This SCV can be set to override the

name of the OpenSSL SSL API library that is loaded when and if needed at run-time to support usage of transport layer security (SSL/TLS AKA SMTP STARTTLS command). The default name of the library is platform specific. You would only set this SCV is for whatever reason IAF DML was using the wrong library name. Although this SCV is dynamic, once the library is loaded, that's it. It is not unloaded and reloaded.
GEM_OPENSSL_LIBRARY_PATH This SCV can be set to override the location of the above two OpenSSL libraries which are loaded when and if needed at run-time to support usage of transport layer security (SSL/TLS AKA SMTP STARTTLS command). The default location of the libraries is platform specific. You would only set this SCV if for whatever reason IAF DML was using the wrong library location. Although this SCV is dynamic, once the library is loaded, that's it. It is not unloaded and re-loaded. GEM_SMTP_ANONYMOUS_TOKEN By default when using AUTH

ANONYMOUS authentication MAIL/SMTP sends the remote SMTP server a short token consisting of random alphanumeric characters. Set this SCV if you need to send a specific token instead.
GEM_SMTP_AUTH_DOMAIN This SCV sets the default authentication domain if none is set with the /DOMAIN qualifier. GEM_SMTP_AUTH_PASSWORD This SCV sets the default authentication password is none is set with the PASSWORD qualifier. GEM_SMTP_AUTH_USERNAME This SCV sets the default authentication username if none is set with the /USERNAME qualifier. GEM_SMTP_OPTIONS This SCV sets the default options if none are set with the /OPTIONS qualifier. GEM_SMTP_PIPELINE_LIMIT The SMTP command pipeline limit. The

default SMTP command pipeline limit is 100 commands if this SCV is not setCommand pipelining is mostly beneficial when high latency network links are used in combination with specifying MANY message recipients. Setting this SCV too high (where just how "high" is not

Language Statements IAF 8.0 DML

6-249

MAIL/SMTP

possible for us to specify in advance) can cause deadlocks which are not under the control of MAIL/SMTP.
GEM_SMTP_SERVER_GSSAPI_HOST Set this SCV to override the

hostname portion of the service principal name which MAIL/SMTP constructs when doing AUTH GSSAPI (Kerberos) authentication.
GEM_SMTP_SERVER_GSSAPI_REALM Set this SCV to override the

Kerberos realm portion of the service principal name which MAIL/SMTP constructs when doing AUTH GSSAPI (Kerberos) authentication.
GEM_SMTP_SERVER_GSSAPI_SERVICE Set this SCV to override the service name portion of the service principal name which MAIL/SMTP constructs when doing AUTH GSSAPI (Kerberos) authentication. If this SCV is not set the default service name is "smtp" as defined by both RFC standard and IANA authority. You may need to override this for nonstandard service names such as those used by Microsoft Exchange Server ("SMTPSVC"). GEM_SMTP_SERVER_GSSAPI_SPN Set this SCV to override the

entire service principal name which MAIL/SMTP constructs when doing AUTH GSSAPI (Kerberos) authentication. This SCV overrides the three SCVs above. On non-Windows platforms the service principal name has the following format "service@hostname" where service is "smtp" by default and "hostname" is the fully qualified hostname of the host to which you are connecting. On Windows platforms the service principal name has the format "
GEM_SMTP_SERVER_NAME This SCV sets the default SMTP server host if none is set with the /SERVER qualifier. This is the most important SCV to set. The others can mostly be ignored, but you definitely want to set this one. GEM_SMTP_SERVER_PORT This SCV sets the default network port to connect to on the remote SMTP server host if none is set with the /PORT qualifier. The default is the port named "smtp" (which is usually port number 25). GEM_SMTP_SERVER_TIMEOUT This SCV sets the amount of inactivity after which the SMTP server is considered to not be responding. The default is 300 seconds. GEM_SMTP_TLS_CHECK_SERVER_CERT The setting of the SCV

determines whether or not MAIL/SMTP checks the server certificate when using transport layer security (SSL/TLS). By default MAIL/SMTP does not check the server certificate.
6-250 Language Statements IAF 8.0 DML

MAIL/SMTP

GEM_SMTP_TLS_CLIENT_CERT_FILE The name of a file which contains the client certificate in PEM format which is loaded when using transport layer security (SSL/TLS). GEM_SMTP_TLS_PRIVATE_KEY_FILE The name of a file which

contains your private key in PEM format which is loaded when using transport layer security (SSL/TLS).
GEM_TLS_TRUST_CERT_DIR The directory which contains files with specially hashed names and which contain the trust certificatesin PEM format which are loaded when using transport layer security (SSL/TLS). GEM_TLS_TRUST_CERT_FILE The name of a file which contains the

trust certificates in PEM format which are loaded when using transport layer security (SSL/TLS). This SCV overrides the GEM_TLS_TRUST_CERT_DIR SCV.

SMTP Server Feature Determination

If you are wondering whether or not your SMTP server supports 8BITMIME or what forms of authentication it supports, it is a simple matter to determine this. TELNET to port 25 (or whatever port your SMTP server is running on) on your server machine and type:
EHLO type.something.that.looks.like.a.host.name.here.

Your SMTP server will then display what features it supports. If that does not elicit a positive response, then try the following instead:
HELO type.something.that.looks.like.a.host.name.here

Then:
HELP

In both cases type QUIT when you are finished.

QUIT

If the EHLO command is not recognized, then your SMTP server should probably be replaced with modern software. However IAF DML can still send mail via SMTP servers that do not support ESMTP. ESMTP support is highly desirable, but not required. Plain old SMTP is acceptable. For example:
C:\ telnet smtp.mydomain.com 25

220 smtp.mydomain.com Microsoft ESMTP MAIL Service, Version: 6.0.3790.1830 ready at Wed, 26 Sep 2007 06:31:58 -0400

Language Statements IAF 8.0 DML

6-251

MAIL/SMTP

EHLO type.anything,you.like.here.com 250-smtp.mydomain.com Hello [192.168.42.111] 250-TURN 250-SIZE 20971520 250-ETRN 250-PIPELINING 250-DSN 250-ENHANCEDSTATUSCODES 250-8bitmime 250-BINARYMIME 250-CHUNKING 250-VRFY 250-X-EXPS GSSAPI NTLM LOGIN 250-X-EXPS=LOGIN 250-AUTH GSSAPI NTLM LOGIN 250-AUTH=LOGIN 250-X-LINK2STATE 250-XEXCH50 250 OK QUIT 221 Closing connection. Good bye.

The SMTP server above: 1. 2. Supports ESMTP. Supports the TURN command to turn the link around which might be useful to another SMTP server, but is not useful to a client such as IAF DML. Reports that the maximum message size it is willing to accept is 20971520 bytes. This is information which IAF DML does not currently utilize. Supports the ETRN command, an enhanced form of TURN. Supports command PIPELINING for efficient use of high latency network connections. IAF DML supports command pipelining and will place up to the number of commands set with the GEM_SMTP_PIPELINE_LIMIT SCV (which defaults to 100) into the pipeline at once. Note that pipeline extremely large number of

3.

4. 5.

6-252

Language Statements IAF 8.0 DML

MAIL/SMTP

commands which cause the TCP window size to be exceeded can lead to deadlocks. IAF DML only pipelines while sending MAIL FROM and RCPT TO commands. 6. 7. 8. 9. Supports delivery status notification. IAF DML can utilize this feature when available. Supports enhanced status codes. IAF DML utilizes this feature when available. Supports 8-bit mime. IAF DML can utilize this feature when available. Supports binary mime and data chunking. These two features are codependent. IAF DML does not currently utilize this feature.

10. Supports the VRFY command (likely only to the extent to report that it doesn't truely support it when an attempt is made to use it). This feature is highly unlikely to be truly supported by any Internet connected host! IAF DML has no need to utilize this feature. 11. Supports GSSAPI (usually means Kerberos in practice, but this is transparent to the client), NTLM and LOGIN authentication. 12. Supports various Microsoft proprietary features (all the ones that start with the letter X in this case). This is an Exchange server. 13. Does not support transport layer security (SSL/TLS) negotiation. The STARTTLS feature is absent. 14. Does not support CRAM-MD5, DIGEST-MD5 PLAIN or ANONYMOUS authentication. These are absent from the AUTH list.

GEMTRACE Logging
The MAIL/STMP statement logs just about everything it does to the GEMTRACE log at the VERBOSE log level. This includes every single character sent to and received from the remote SMTP server from the very beginning of the session to the very end. If the session is encrypted with SSL/TLS, only unencrypted data is logged.

Language Statements IAF 8.0 DML

6-253

MENU
Syntax
MENU [database_handle.][system_name:]facility_name

Category
Screen input and output

Description
This statement executes the specified facilitys menu. IAFs System Definition Editor facilitates defining systems, facilities, and facility menus. A system is a functional hierarchy of facilities and sub- facilities. A facility is a functionally cohesive sub-set of the given system.
database_handle

This is the handle for the database that holds the specified facility. It is necessary to include a database handle only if you have invoked multiple databases, and the specified facility is not in the current default database.
system_name

This is the name of the system in which the given facility exists. If the MENU statement does not specify a system name, IAF uses the default system. To specify the default system, execute the following statement at the IAF command line prompt (GEM> by default):
SET SYSTEM system_name

If the MENU statement does not specify a system name, and execution of the SET SYSTEM has not taken place to explicitly establish a default system, the default system is the current system. To show the default systems name, execute the SHOW SYSTEM statement at the IAF command line.
facility_name

This is the name of the facility whose menu IAF is to invoke.

Example
MENU ACCOUNTS_PAYABLE:REPORTS

6-254

Language Statements IAF 8.0 DML

MENU

This example causes IAF to execute the menu associated with the REPORTS facility in the ACCOUNTS_PAYABLE system in the current default database.

Related Topics
The following references contain information pertaining to the MENU statement: This chapters discussions of the SET SYSTEM and SHOW SYSTEM statements. The discussion of IAFs System Definition Editor in the IAF System Reference Manual.

Language Statements IAF 8.0 DML

6-255

MESSAGE

MESSAGE
Syntax
MESSAGE [/qualifiers] [database_handle.] message_name [,argument1[,argument2[,...]]]

or
MESSAGE

Category
Screen input and output

Description
This statement causes IAF to display the specified message in the message display window at the bottom of the screen, or to clear an existing message if the MESSAGE statement does not specify a message name. If the MESSAGE statement specifies a message name, it indicates a message defined via the Data Definition Editors MESSAGE maintenance facility. The MESSAGE statement can substitute data available at run-time for tokens in the given message.
database_handle

This is the handle of the database in which the specified message exists. It is necessary to include a database handle only if you have invoked multiple databases, and the specified message does not exist in the current default database.
message_name

This is the name of a message defined via the Data Definition Editors message maintenance facility.
argument1[,argument2[,...]]

This is one or more arguments that IAF is to substitute for mask tokens in the given message. IAF substitutes the argument specifications on a character-by-character basis.

6-256

Language Statements IAF 8.0 DML

MESSAGE

Qualifiers
The following qualifiers are valid for use with the MESSAGE statement:
/BELL

This qualifier causes IAF to sound the system bell upon executing the MESSAGE statement. By default, IAF sounds no bell.
/CONFIRM

This qualifier causes IAF to display the given message and then wait for end user input, confirming that the end user has seen the message, before removing the message from the screen. The difference between the /CONFIRM qualifier and the /WAIT qualifier is that the /CONFIRM qualifier causes the program to pause at the message display point as opposed to the next input or next message display (whichever comes first) as is the case with the /WAIT qualifier.
/FACILITY

This qualifier causes IAF to display the handle of the database in which the message is defined before the actual message text.
/IDENTIFIER

This qualifier causes IAF to display the name of the message before the actual message text.
/SEVERITY

This qualifier causes IAF to display the messages severity before the actual message text. Message severity indicators can be fatal (F), error (E), warning (W), information (I), or success (S).
/WAIT

This qualifier indicates that IAF is not to overwrite the current message with another message without receiving a response (i.e. input) from the end user.

Examples
Assuming the Data Definition Editor contains the following message definitions: Message Name SOYBEAN Severity I Soybean Source Text

Language Statements IAF 8.0 DML

6-257

MESSAGE

Message Name NODEPT OVERDRAWN

Severity E W

Text Department !Tx does not exist Customer overdrawn by !$@@@@.0@

the following MESSAGE statement:

MESSAGE SOYBEAN

results in the following text display:

Soybean Source

The following MESSAGE statement:

MESSAGE/IDENTIFIER NODEPT, SYS

results in:
%NODEPT, Department Sys does not exist

and:
MESSAGE/SEVERITY OVERDRAWN, 22.3

results in:
%W, Customer overdrawn by $22.30

Related Topics
The following references contain information pertaining to the MESSAGE statement: This chapters discussion of the ERROR and PRINT statements. The discussion of masks in this manuals INPUT AND OUTPUT MASKS appendix. The discussion of messages in the IAF System Reference Manual and in this manuals DML Metadata Commands chapter.

6-258

Language Statements IAF 8.0 DML

MODIFY FACILITY

MODIFY FACILITY
Syntax
MODIFY FACILITY system_name:facility_name [/DELETE_ROLES="role_name[,role_name[,...]]]" [/ADD_ROLES="role_name[,role_name[,...]]]" [/qualifiers]

Category
Program flow

Description
The MODIFY FACILITY DML command was changed to accommodate the new roles associated with the facility for the metadata dump/update report.

Qualifiers
Two optional qualifiers /DELETE_ROLES /ADD_ROLES have been added. The prior existing MODIFY FACILITY command was:
MODIFY FACILITY system_name:facility_name [/qualifiers]

This has been changed to include the new role qualifier as follows:
MODIFY FACILITY system_name:facility_name [/DELETE_ROLES="role_name[,role_name[,...]]]" [/ADD_ROLES="role_name[,role_name[,...]]]" [/qualifiers]

Example
MODIFY FACILITY sys1:fac1 /DELETE_ROLES="role1,role2,role3" /ADD_ROLES="role4,role5"

Language Statements IAF 8.0 DML

6-259

MODIFY ROLE

MODIFY ROLE
Syntax
MODIFY ROLE role-name [/DESCRIPTION=description] [/ADD_FACILITIES=add-facilities] [/DELETE_FACILITIES=delete-facilities]

Category
Program flow

Description
This DML statement modifies the description of a role and the facilities associated with a role in the current database. role-name A literal, quoted literal or variable containing the name of the role. A role name is a character string with max length of thirty-one characters and is case insensitive. description A literal, quoted literal or variable containing the new description of the role. add-facilities A literal, quoted literal or variable containing a comma separated list of 'system:facility' pairs. The specified set of system:facility pairs will be associated with the role. delete-facilities A literal, quoted literal or variable containing a comma separated list of system:facility pairs. The specified set of system:facility pairs will be disassociated from the role. The addition and deletion of the role from the facilities is not automatic with the modification of the role. They are separate transactions. The
6-260 Language Statements IAF 8.0 DML

MODIFY ROLE

facilities specified in add-facilities and delete-facilities are checked at run-time before the role is modified to ensure that They are syntactically valid They exist in the database The user has modify access to them. If any of these checks fail, then the role is not modified. Facility deletions are done before facility additions. Not withstanding the up-front checks, if for any reason the addition or deletion of the role from the specified facilities should still fail, said additions and or deletions will stop with the first failure and no further additions or deletions will take place. For metadata auditing purposes, this statement is audited as a MODIFY ROLE role-name statement followed by successive MODIFY FACILITY add-facility /ADD_ROLE=role-name and/or MODIFY_FACILITY delete-facility /DELETE_ROLE=role-name statements.

Example
MODIFY ROLE "SALES" /description=This is the new description

This replaces the SALES role description with a new one.

MODIFY ROLE "SALES" / ADD_FACILITIES ="Sys1:Fac1,Sys2:Fac2,,SysN:FacN"

This adds the list of facilities to the role "SALES".

MODIFY ROLE "SALES" / DELETE_FACILITIES="Sys1:Fac1,Sys2:Fac2,,SysN:FacN"

This deletes the list of facilities from the role "SALES".

Language Statements IAF 8.0 DML

6-261

OPEN

OPEN
Syntax
OPEN unrelated_table_file AS datafile_handle [/qualifiers]

Category
Data access

Description
This statement enables you to dynamically open an unrelated table file, and is valid for use only with unrelated RMS table files when running IAF on OpenVMS. IAF considers the given unrelated table to be part of a pseudo-database having the reserved handle RMS. The default filetype for unrelated table files is .dat. A description file detailing the layout of the records in the table that the OPEN statement specifies must exist in the same directory as the unrelated table file. The description files name must be the same as the datafiles name, but with a filetype of .gem_dsc, unless the OPEN statement includes the /DESCRIPTION qualifier to specify otherwise. By default, the OPEN statement has no effect on the %STATUS special variable because any errors resulting from the OPEN statements execution are signaled. However, it is possible to trap signaled errors to the %STATUS special variable via the BEGIN_SIGNAL_TO_STATUS statement. For details, refer to this chapters description of the BEGIN_SIGNAL_TO_STATUS statement.
unrelated_table_file

This is the name of the unrelated table file to open.

datafile_handle

This is the handle to use within IAF when referencing the given unrelated table file.

Qualifiers
The following qualifiers are valid for use with the OPEN statement:
/DESCRIPTION=filename

6-262

Language Statements IAF 8.0 DML

OPEN

This qualifier enables you to specify the name of an alternate description file that describes the given unrelated table file. This qualifier is useful when IAF is processing many unrelated table files that have the same record layout but different names. You can also use this qualifier if the name of the unrelated table file to open will be known only at run-time. Appending this qualifier to the OPEN statement has the same effect as defining the GEM_RMS_METADATA_n System Customization Variable (SCV) for a given unrelated table file at GEM start-up time.
/READ_ONLY

This qualifier causes IAF to open the unrelated table file in a read-only mode. The read-only mode prevents updates of any kind from being made to the file. You must include this qualifier when attempting to open a file to which the end user has only read-only access.

Example
OPEN CUSTOMER_MASTER AS CUST

Related Topics
The following references contain information pertaining to the OPEN statement: This chapters discussions of the BEGIN_SIGNAL_TO_STATUS, CLOSE, and END_SIGNAL_TO_STATUS statements. The discussions of the %STATUS special variable in this manuals SPECIAL VARIABLES AND VALUE SYMBOLS chapter. The discussion of System Customization Variables in the IAF guide that applies to your operating system. The discussions of unrelated tables and security options in the Guide to Using IAF with RMS.

Language Statements IAF 8.0 DML

6-263

OPEN_APPLICATION

OPEN_APPLICATION
Syntax
OPEN_APPLICATION application AS handle

Category
Client/Server environment.

Description
This statement opens the specified application, thereby making it available for subsequent connections via the CONNECT statement and stored procedure execution via the EXECUTE statement. The OPEN_APPLICATION statement's application parameter specifies the address of the broker (the broker IPC_name), username and password of the user, the name of application to open, and optionally, the name of the database in which to search for a given stored procedure. This statement causes IAF to authenticate the user with the broker based upon the specified username/password combination. If the authentication succeeds, and the specified broker has knowledge of the given application, IAF allows access to application via the specified handle. The applications handle shares the same name space as the datafiles datafile_id. IAF displays an error if the specified application handle is the same as the database handle of a previously invoked database.

Parameters
application

The format to use for the application specification is the same as that for the INVOKE statement except that the database_name component of the OPEN_APPLICATION statement's syntax is optional. Following is the format to use for the OPEN_APPLICATION statement's application parameter specification:
[broker_IPCname][\username\password]::application_name[:database_name]

where broker_IPCname is the network address of the broker, and indicates a node name and optional transport-specific information. For details regarding broker_IPCnames, refer to the Client/Server Environment Chapter in either the IAF User Guide or in the Guide to

6-264

Language Statements IAF 8.0 DML

OPEN_APPLICATION

Using IAF Enterprise Server on Windows, or the Guide to Using IAF for your platform. Specifying a database name causes IAF to search only that database for the stored procedure that a given EXECUTE statement specifies. If you do not specify a database name, IAF searches for the stored procedure in each database that the application references.
handle

This is the handle of the application, and is used by the CONNECT statement and the EXECUTE statement to specify the application against which to operate. You can specify the connect handle via a constant or a variable. The handle is global to a Client process. Therefore, if a DML program executes OPEN_APPLICATION and CONNECT statements with a given connect handle, subsequent programs can reference the connect handle when executing a stored procedure via the EXECUTE statement. For details on using the connect handle when executing a stored procedure, refer to this chapter's discussion of the EXECUTE statement's /HANDLE qualifier.

Examples
OPEN_APPLICATION "TCP,MONDO,6065\TEST\*::SALES_ORDERS" AS ORDERS CONNECT ORDERS

This example causes IAF to display a window prompting the end user to enter a password, and allowing the end user to enter a node name and username other than MONDO and TEST, respectively. If the end user enters valid login access control information, IAF connects the Client to the Server Application named SALES_ORDERS on the specified node, establishes ORDERS as the connect handle, and retains the session information.

Language Statements IAF 8.0 DML

6-265

OPEN_TAB

OPEN_TAB
Syntax
OPEN_TAB [/URL=[String Expression]/WEB_APP=[String Expression]/FACILITY=[String Expression]/PERFORM=[String Expression]][/DESC=[String Expression]/NEW_WINDOW]

Category
Text file management.

Description
This command allows opening either a TAB within an iBrowser session or another browser session with either a URL or a WEB_APP specification.

Qualifiers
/URL

This is the URL to be opened.

/WEB_APP

This is the Web Application to be opened.

/FACILITY

This is the facility name to be opened.

/PERFORM

This is the DML program to be executed.

/DESC

This is the description to be displayed on the new TAB opened.

/NEW_WINDOW

This qualifier specifies that the URL or WEB_APP will be opened in a new window. This option is only valid with URL or WEB_APP qualifiers.

6-266

Language Statements IAF 8.0 DML

OPEN_TAB

The following mutually exclusive qualifiers are valid for use with the OPEN_TAB statement: /URL /WEB_APP /FACILITY /PERFORM Similarly, DESC and NEW_WINDOW are mutually exclusive.

Language Statements IAF 8.0 DML

6-267

OPEN_TEXT

OPEN_TEXT
Syntax
OPEN_TEXT [/qualifier] filename AS tag

Category
Text file management.

Description
This statement causes IAF to open the specified text file. By default, the OPEN_TEXT statement has no effect on the %STATUS special variable because any errors resulting from the OPEN_TEXT statements execution are signaled. However, it is possible to trap signaled errors to the %STATUS special variable via the BEGIN_SIGNAL_TO_STATUS statement. For details, refer to this chapters description of the BEGIN_SIGNAL_TO_STATUS statement.
filename

This is the name of the text file that IAF is to open.

tag

This is the handle that other text file statements are to use for the opened file.

Qualifiers
The following mutually exclusive qualifiers are valid for use with the OPEN_TEXT statement:
/APPEND

This qualifier indicates that IAF is to write to the end of the file as opposed to overwriting the start of the file.
/CREATE

This qualifier indicates that IAF is to create a new version of the given file before opening it. If the file does not already exist, IAF creates it.
/PDF

6-268

Language Statements IAF 8.0 DML

OPEN_TEXT

This qualifier, when used with the /CREATE qualifier, causes a Portable Document File (PDF) to be created instead of a text file. The /PDF qualifier cannot be used with the /APPEND qualifier or in the absence of the /CREATE qualifier. (However, the DML compiler will intentionally not complain about this at compile time. Instead, you will receive a file not found error at run-time.) Note that an end of file error will be returned at run-time if you attempt to use the READ_LINE or REWIND statements with a document opened using the /PDF qualifier. No support for reading PDF files is supplied. The PDF qualifier has many options. The entire option list as a whole should be enclosed in parenthesis. Each option value may be a quoted string, a variable, or an expression containing table-field references, functions, operators, etc. Some options require textual input and others require numeric input. For numeric values, unless otherwise stated, both integer and floating point values are accepted. For detailed descriptions of all PDF qualifier options, please refer to the detailed description of the /PDF qualifier in this manuals form qualifiers section. Also, please refer to the PDF Reports and PDF file production section of this manual for more information concerning IAF and PDF production.

Example
OPEN_TEXT charter.txt AS CHART

Related Topics
The following references contain information pertaining to the OPEN_TEXT statement: This chapters discussions of the BEGIN_SIGNAL_TO_STATUS, CLOSE_TEXT, END_SIGNAL_TO_STATUS, READ_LINE, REWIND_TEXT, WRITE, and WRITE_LINE statements. The discussion of the %STATUS special variable in this manuals SPECIAL VARIABLES AND VALUE SYMBOLS chapter.

Language Statements IAF 8.0 DML

6-269

OPEN_URL

OPEN_URL
Syntax
OPEN_URL /URL=string expression {/DESC=string expression | /NEW_WINDOW }

/URL specifies the web page to open and is a required qualifier. /DESC provides a brief description of the web page that will be opened. It is used in the tab that is created to display the web page. /NEW_WINDOW specifies that the web page is not to be placed in a new tab, but is to be displayed in a new browser window. /DESC and /NEW_WINDOW are mutually exclusive. One or the other must be specified, but not both.

Description
The new OPEN_URL command causes iBrowser to open the given URL as a web page. This command is specific to iBrowser and generates an error on other platforms.

6-270

Language Statements IAF 8.0 DML

PERFORM

PERFORM
Syntax
PERFORM [/NODEADLOCK_EXIT] form_name [(argument1[,argument2[,...]])]

or
PERFORM [/BATCH[=PRINT]] form_file_spec [(argument1[,argument2[,...]])]

or
PERFORM [/BATCH[=PRINT]][/NODEADLOCK_EXIT] form_file_spec & form_name [(argument1[,argument2[,...]])]

or
PERFORM /FACILITY DB.SYS:FAC [(argument1[,argument2[,...]])]

or
PERFORM /ARRAY[=count] #array()[form_name] [(argument1[,argument2[,...]])]

Category
Program flow

Description
This statement causes IAF to execute the specified form. The first syntax requires the specified form to exist in the DML file that IAF is currently executing. Appending the /BATCH qualifier to the DML PERFORM statement facilitates executing IAF forms as batch jobs. To execute a form in batch mode, IAF actually executes the form twice. First, IAF executes the form, except for any PERFORM statements it includes, in interactive mode. During this first execution, IAF records all end user responses to inputs and places them in a data deck in a command file (filetype .COM). Second, IAF executes the entire form, including any PERFORM statements, in batch mode and feeds the form the input responses from the data deck.

Language Statements IAF 8.0 DML

6-271

PERFORM

The second syntax causes IAF to execute the first form in the specified DML file. The third syntax causes IAF to execute the specified form in the specified DML file. If a form that the PERFORM statement executes returns a status, IAF places the status in the %STATUS special variable, thereby making it available to the form in which the PERFORM statement resides. However, by default, any errors resulting from the PERFORM statements execution (e.g. the specified file does not exist) are signaled and therefore, have no effect on the %STATUS special variable. It is possible to change the default behavior and trap signaled errors to the %STATUS special variable via the BEGIN_SIGNAL_TO_STATUS statement. For details, refer to this chapters description of the BEGIN_SIGNAL_TO_STATUS statement.
form_file_spec

This is the file specification for the DML file that holds the form that IAF is to execute. The specification must indicate a compiled DML file (filetype .dmc) or a DML source file (filetype .dml). You can use the SET PERFORM statement to specify whether IAF is to search for compiled DML files only, source DML files only, or first one filetype and then the other. You can override the filetype specification that the SET PERFORM statement specifies by explicitly including a filetype (i.e. .dmc or .dml) with the PERFORM statements form file specification.
form_name

This is the name of the form that IAF is to execute. If the PERFORM statement does not include a form file specification, the form must exist in the DML file that IAF is currently executing. Otherwise, the form must exist in the specified DML file.
(argument1[,argument2[,...]])

This is one or more arguments to pass to the specified form. Single variables, table fields, and DML parameters are implicitly read-write unless enclosed in parentheses, in which case they are read-only. All other arguments are read-only. Therefore, in order for a form to modify an argument passed to it, the argument must be a variable, table field, or DML parameter that is not enclosed in parentheses. To cause a single variable, table field, or DML parameter to be read-only, enclose it in parentheses (nested within those that the standard syntax requires). If at all possible, it is advisable to make table fields and DML parameters read-only. This prevents an unnecessary write to the table field
6-272 Language Statements IAF 8.0 DML

PERFORM

or DML parameter. By default, IAF writes to the table field or parameter subsequent to completing execution of the routine, regardless of whether or not the routine modified the argument. Note that a PERFORM statement that passes arguments during a read-only transaction should enclose the arguments in parentheses to ensure that no argument updates take place.

Qualifiers
The following qualifiers are valid for use with the PERFORM statement:
/BATCH[=PRINT]

This qualifier indicates that the specified form file is to execute as a batch job. Briefly, batch processing entails prompting for any input as normal, but not performing any subordinate forms. For a full description of IAFs batch processing function, refer to the IAF guide that applies to your operating system. When performing a form via the PERFORM/BATCH statement, IAF appends the /NOIMPLICIT qualifier to the database definition statements that it writes to the resulting command file if the given database was originally invoked with the /NOIMPLICIT qualifier appended. Additionally, if the GEM_READ_ONLY System Customization Variable (SCV) is defined for the user executing the PERFORM/BATCH statement, IAF writes the appropriate GEM_READ_ONLY SCV definition to the command file. Specifying the /BATCH qualifier without the PRINT keyword causes IAF to display a window prompting for the entries that the following table lists and describes. Entry File Name Submit On Queue Description The name that IAF is to use for the command file it produces for the batch job. The date and time at which submission of the batch job is to take place. The name of the batch queue to which to submit the batch job.

Language Statements IAF 8.0 DML

6-273

PERFORM

Specifying the /BATCH=PRINT qualifier causes IAF to display a window prompting for the entries that the following table lists and describes. Entry Report Print Queue Description For REPORT forms, this is the name of the print queue to which to send the report listing (.lis file) that is the result of executing the given REPORT form. For REPORT forms, this is the form type to use when printing the report. For REPORT forms, this is the number of copies of the report to print. The name that IAF is to use for the command file it produces for the batch job. The date and time at which submission of the batch job is to take place. The name of the batch queue to which to submit the batch job.

Form Type Copies Batch File Name Submit On Batch Queue

For REPORT forms, the /BATCH=PRINT qualifier queues the resultant report listings directly to the specified print queue at the end of the batch job. The following methods are also available for sending report listings (.lis files) to print queues: Use the FILES statement (FILES/PRINT_ONLY/NOQUERY report_name.lis). Use the CLI statement to execute a system command if you require the use of system print qualifiers. The GEM_PRINT_QUEUE, GEM_PRINT_FORM, and GEM_PRINT_COPIES SCVs, if defined, indicate the default queue, form type, and number of copies, respectively, to appear as default responses in the batch window that IAF displays as a result of executing the PERFORM/BATCH=PRINT statement.
/BATCH[=PRINT]

When the /FACILITY qualifier is used, the form-name portion of a PERFORM statement must reference a facility instead of a form name. The facility is referenced using standard IAF facility syntax of:

6-274

Language Statements IAF 8.0 DML

PERFORM

[[database-handle.][system-name:]]facility-name

For example:
#FAC = SYS:FAC SWITCH /FACILITY #FAC (#P1,#P2,#P3)

The user must have EXECUTE access to the specified facility in order to perform the procedure. The form-file specification and form-name to be performed is taken from the facilitys menu-file and menu-form respectively. If these are blank, but the facility dml statement is not, then the facility dml statement is executed instead. In the event that the PERFORM statement specifies parameters and the facility dml is executed rather than a form, the parameters are evaluated, but not used. If the facility dml is itself a PERFORM statement, then the parameters specified on that statement are used. It is not be permitted to combine the /FACILITY qualifier with any other qualifiers (such as /BATCH).
/FACILITY

When the /FACILITY qualifier is used, the form-name portion of a PERFORM statement must reference a facility instead of a form name. The facility is referenced using standard IAF facility syntax of:
[[database-handle.][system-name:]]facility-name

For example:
PERFORM /FACILITY DB.SYS:FAC (#P1,#P2,#P3)

The user must have EXECUTE access to the specified facility in order to perform the procedure. The form-file specification and form-name to be performed is taken from the facilitys menu-file and menu-form respectively. If these are blank, but the facility dml statement is not, then the facility dml statement is executed instead. In the event that the PERFORM statement specifies parameters and the facility dml is executed rather than a form, the parameters are evaluated, but not used. If the facility dml is itself a PERFORM statement, then the parameters specified on that statement are used. It is not be permitted to combine the /FACILITY qualifier with any other qualifiers (such as /BATCH).
/NODEADLOCK_EXIT

This qualifier indicates that, in the event of a deadlock situation, the current form is to exit, and IAF is to trap the event that caused the

Language Statements IAF 8.0 DML

6-275

PERFORM

deadlock situation. Additionally, IAF is to return %DEADLOCK in the %STATUS special variable. Note that IAF can trap the deadlock event only if there are no transactions outstanding (i.e. IAF has rolled back any transaction, real or pseudo, that caused the deadlock situation). If the PERFORM statement does not include this qualifier, IAFs default behavior when a deadlock situation occurs is to automatically exit all calling forms, and roll back all transactions until there is no longer a transaction in progress. Therefore, this qualifier facilitates maintaining control within a form file even when a performed form within the file results in a deadlock situation. For more information regarding deadlocks and transactions, refer to the IAF Users Guide. Note that the /NODEADLOCK_EXIT qualifier and the /BATCH qualifier are mutually exclusive.
/ARRAY

The fourth syntax causes IAF to execute the specified form (the form name is optional, if omitted, the first form in the array is executed) whose source code is contained in the specified array variable. The DML source code starts at array element number one and continues to the last used element in the array or to the element specified with the optional /COUNT qualifier. The content of the array appears to the compiler to be an entire .DML form file. It may therefore contain anything that a .DML form file on disk may contain, including multiple forms.

Examples
PERFORM SHOW_CUSTOMERS

This example causes IAF to execute the current DML files SHOW_CUSTOMERS form.
PERFORM sales_order_entry.dml

This example causes IAF to execute the first form in the sales_order_entry.dml file.
PERFORM DELETE_OLD_ORDERS (#CUTOFF_DATE)

This example causes IAF to execute the current DML files DELETE_OLD_ORDERS form and to pass to it the #CUTOFF_DATE variable as an argument.
PERFORM inquiries.dmc ORDER_INQUIRY (CUSTOMERS(ID), #ORDER_STATUS)

6-276

Language Statements IAF 8.0 DML

PERFORM

This example causes IAF to execute the ORDER_INQUIRY form that resides in the inquiries.dmc file and to pass to it the CUSTOMERS(ID) table field and the #ORDER_STATUS variable as arguments. The PERFORM/ARRAY statements let you perform the contents of a DML array as if it is a DML form file.
Clear_Array #Array() #Array(1) = "Procedure_Form A(#A)" #Array(2) = " Print ('Form A - ' & #A)" #Array(3) = "End_Form" #Array(4) = "Procedure_Form B(#B)" #Array(5) = " Print ('Form B - ' & #B)" #Array(6) = "End_Form" Perform #Array() B("ABC")

Clear_Array #Array() #Array(1) = "Procedure_Form A(#A)" #Array(2) = " Print ('Form A - ' & #A)" #Array(3) = "End_Form" #Array(4) = "Procedure_Form B(#B)" #Array(5) = " Print ('Form B - ' & #B)" #Array(6) = "End_Form" #Array(98) = "Trailing junk to be ignored by using optional /Array qualifier value" #Array(99) = "Ditto" Perform/Array=6 #Array() B("ABC")

Related Topics
The following references contain information pertaining to the PERFORM statement: This chapters discussions of the BEGIN_SIGNAL_TO_STATUS, END_SIGNAL_TO_STATUS, SET PERFORM, SHOW_PERFORM, SWITCH, and SWITCH_BASE statements. The discussions of the %STATUS special variable and value symbols in this manuals SPECIAL VARIABLES AND VALUE SYMBOLS chapter. The discussion of forms and form qualifiers in this manuals Forms and Form Qualifiers chapter and in the IAF System Reference Manual.

Language Statements IAF 8.0 DML

6-277

PERFORM

The discussions of batch processing and System Customization Variables in the IAF guide that applies to your operating system. The discussion of deadlocks and transactions in the IAF Users Guide.

6-278

Language Statements IAF 8.0 DML

PWD

PWD
Syntax
PWD

Category
Miscellaneous

Description
Shows the users current working directory (default directory). See also the SHOW DEFAULT and SHOW WD statements and the %WD special variable.

Language Statements IAF 8.0 DML

6-279

PRINT

PRINT
Syntax
PRINT [/qualifiers] expression

Category
Screen input and output

Description
This statement causes IAF to display the given expressions value in the message display area at the base of the screen. If IAF is currently displaying a message when this statement executes, IAF displays a question mark (?) to the right of the message to let the end user know that IAF is waiting to display another message. The end user can press any key to display the underlying message. The PRINT statement accepts only a single expression. However, the expression can include multiple components concatenated via the ampersand (&) operator. Parentheses must enclose a concatenated expression.

Qualifiers
The following qualifiers are valid for use with the PRINT statement:
/BELL

This qualifier causes IAF to trigger a system bell when the given PRINT statement executes.
/CONFIRM

This qualifier causes IAF to display the given message and then wait for end user input, confirming that the end user has seen the message, before removing the message from the screen. The difference between the /CONFIRM qualifier and the /WAIT qualifier is that the /CONFIRM qualifier causes the program to pause at the message display point as opposed to the next input or next message display (whichever comes first) as is the case with the /WAIT qualifier.

6-280

Language Statements IAF 8.0 DML

PRINT

/NOBELL

This qualifier causes IAF not to trigger a system bell when the given PRINT statement executes. This is the PRINT statements default behavior.
/NOWAIT

This qualifier overrides the default waiting period that IAF uses when a PRINT statement executes, and indicates that IAF can overwrite the current message with a subsequent message without end user confirmation.
/WAIT

This qualifier specifies that IAF may not overwrite the current message with a subsequent message without a response from the end user. This is the PRINT statements default behavior.

Examples
PRINT #A PRINT (Total: & #TOT_VAL) PRINT /BELL CUSTOMERS(NAME)

Related Topics
The following references contains information pertaining to the PRINT statement: This chapters discussions of the ERROR and MESSAGE statements.

Language Statements IAF 8.0 DML

6-281

QUERY

QUERY
Syntax
QUERY [/qualifier] [database_handle.][table_name[(field_name1[,field_name2[,...]]) ]]

Category
Utilities and program development

Description
This statement enables you to invoke IAFs Query By Forms interface, which is a utility that facilitates record addition, modification, and deletion while viewing one record at a time. Note that you must attach to a database prior to executing the QUERY statement for IAF to invoke the Query By Forms utility. If the QUERY statement does not specify the table on which the Query By Forms utility is to operate, IAF displays a window enabling the end user to specify the database and table(s) upon which the utility is to operate. The end user can then select the non-PID fields that the utility is to include in its query display. If the QUERY statement does specify the table on which the Query By Forms utility is to operate, IAF bypasses the aforementioned window and displays as many of the specified tables fields as the query display can vertically accommodate.
database_handle

This is the handle for the database in which the table on which IAF is to perform the query resides. It is necessary to include a database handle only if you have invoked multiple databases, and the specified table does not exist in the current default database.
table_name

This is the name of the table on which the Query By Forms utility is to operate.
(field_name1[,field_name2[,...]])

6-282

Language Statements IAF 8.0 DML

QUERY

This is the name of one or more of the specified tables fields that the Query By Forms utility is to include in its query display.

Qualifier
The following qualifier is valid for use with the QUERY statement:
/READ_ONLY

This qualifier causes the query to operate in read-only mode. This qualifier is useful in situations in which an end user is to have read access to the records in a given table but is not to be allowed to delete or modify the existing records, or add new records to the table.

Examples
QUERY MEMBERS QUERY/READ_ONLY

Data Auditing
Use the GEM_QBF_DATA_AUDIT SCV to enable QBF data auditing on all table fields by default.

Example
GEM_QBF_DATA_AUDIT=TRUE

Related Topics
The following references contain information pertaining to the QUERY statement: This chapters discussion of the UTILITIES statement. The discussion of the Query interface in the IAF System Reference Manual.

Language Statements IAF 8.0 DML

6-283

RANDOMIZE

RANDOMIZE
Syntax
RANDOMIZE

Category
Miscellaneous

Description
Seeds the random number generator. See also the RANDOM function.

6-284

Language Statements IAF 8.0 DML

READ_LINE

READ_LINE
Syntax
READ_LINE tag [/TARGET=target_spec]

Category
Text file management

Description
This statement causes IAF to read a record from the given text file, which was previously opened via the OPEN_TEXT statement. When execution of the READ_LINE statement takes place within a form, IAF places the operations completion status in the %STATUS special variable. If the operation is successful, IAF places the %SUCCESS status in the %STATUS special variable. Therefore, to determine if the operation failed, check %STATUS for a value other than %SUCCESS (i.e. check for %STATUS <> %SUCCESS).
tag

This is the handle by which the READ_LINE statement references the given text file, and is the handle that was specified via the OPEN_TEXT statement when the text file was opened.

Qualifier
The following qualifier is valid for use with the READ_LINE statement:
/TARGET=target_spec

This qualifier indicates the location in which IAF is to place the record that it reads as a result of executing the READ_LINE statement. The target specification must indicate a writable data element, such as a table field or variable. If the READ_LINE statement does not specify a /TARGET qualifier, IAF reads the record but does not store it anywhere.

Examples
OPEN_TEXT addresses.txt AS ADDR READ_LINE ADDR OPEN_TEXT errors.txt AS ERRORS

Language Statements IAF 8.0 DML

6-285

READ_LINE

READ_LINE ERRORS /TARGET=#ERROR_TEXT

Related Topics
The following references contain information pertaining to the READ_LINE statement: This chapters discussions of the OPEN_TEXT, CLOSE_TEXT, WRITE, and WRITE_LINE statements. The discussions of the %STATUS special variable and value symbols in this manuals SPECIAL VARIABLES AND VALUE SYMBOLS chapter.

6-286

Language Statements IAF 8.0 DML

RECEIVE

RECEIVE
Syntax
RECEIVE resource_name [/qualifiers]

Category
Inter-process communication

Description
This statement enables a process to a receive text message that another process sends via the SEND statement. The process that receives the message must specify the same resource that the SEND statement specifies in order to receive the given message. The SEND, RECEIVE and RELEASE DML statements are implemented on OpenVMS and UNIX platforms only. In order for these statements to properly execute on UNIX platforms, the gem_snrd daemon must be running at the time that the given statement is executed.
resource_name

This is the name of the resource from which to receive the text message.

Qualifiers
The following qualifiers are valid for use with the RECEIVE statement:
/CREATE

This qualifier indicates that if the mailbox that the given resource name indicates does not exist, IAF is to create it.
/GROUP

Specifying this qualifier in conjunction with the /CREATE qualifier indicates that IAF is to create a new mailbox and make the messages that the mailbox receives available to all members of the current group.
/MAILBOX

This qualifier indicates that the current process is to receive text via a mailbox device.

Language Statements IAF 8.0 DML

6-287

RECEIVE

/SYSTEM

Specifying this qualifier in conjunction with the /CREATE qualifier indicates that IAF is to create a new mailbox and make the messages that the mailbox receives available to all members of the system.
/TARGET=#variable_name

This qualifier enables you to specify the name of a target variable in which IAF is to place the received text.
/WAIT

This qualifier indicates that the process is to wait to receive a message until one is available. If the RECEIVE statement does not include this qualifier, and no message is currently available, the RECEIVE statement returns a failure status.

Examples
RECEIVE YELLOW /TARGET=#MESSAGE

This example checks the resource, YELLOW, to determine if a message is available. If a message is available, this example receives it and places it in the #MESSAGE variable. Otherwise, this example returns a failure status.
#NAME=RED RECEIVE #NAME /TARGET=#MESSAGE /WAIT

This example checks the resource, RED, to determine if a message is available. If a message is available, this example receives it and places it in the #MESSAGE variable. Otherwise, this example waits for a message to be sent via the resource, RED.

Related Topics
The following references contain information pertaining to the RECEIVE statement: This chapters discussions of the SEND and RELEASE statements. The discussion of inter-process communication in the IAF Users Guide and the IAF guide that applies to your operating system.

6-288

Language Statements IAF 8.0 DML

RECEIVE_DATA

RECEIVE_DATA
Syntax
RECEIVE_DATA [/HANDLE=connect_handle] [writable_data_element[,...]]

Category
Client/Server environment

Description
This statement allows a IAF Client to retrieve row data from the stored procedure in which a given SEND_DATA statement executes. A stored procedure is typically a PROCEDURE form containing DML code that executes in the context of a stored procedure server. Note that a client/server connection must be established between the client in which the RECEIVE_DATA statement executes and the server in which the SEND_DATA statement specified. If a RECEIVE_DATA statement has not yet executed on the connection, the SEND_DATA statement waits until a RECEIVE_DATA statement executes. When this happens, the IAF Server sends the row data to the client in which the given RECEIVE_DATA statement executed. IAF returns the %STATUS special variable the status of the RECEIVE_DATA execution. The return value can be one of the special values that the following table lists:

Value Symbol

Description

%DATA %NORMAL

Row data has been returned into the writable data element and additional row data is available IAF has returned the last of the row data, and argument data from the stored procedure is available for the Client to receive. No row data or argument data is available for the Client to receive. Remote procedure is currently not running. The stored procedure aborted abnormally.

%EMPTY %NONE %ABORT

Language Statements IAF 8.0 DML

6-289

RECEIVE_DATA

The %NONE is returned if the user performs a RECEIVE_DATA after an END_EXECUTE has been performed.

Qualifiers
/HANDLE=connect_handle

The specified connect_handle is one that the OPEN_APPLICATION statement specified for the application connection. If this qualifier is omitted, IAF uses the default connect handle, if it exists. Otherwise, IAF returns an error message.

Parameters
writable_data_element[,...]

This is one or more writable data element specifications indicating the data element(s) to which IAF is to write the data it receives. Writable data elements can be variables, table fields, or DML parameters. If the RECEIVE_DATA statement does not specify any writable data elements, it is not possible to access the data that the stored procedure returns. The number of writable data element specifications that the RECEIVE_DATA statement includes should be the same as the number of data elements specified for the given stored procedure.

Example
RECEIVE_DATA /HANDLE=#FINA #CUST_ID, #CUST_NAME

Related Topics
The following references contain information pertaining to the RECEIVE_TABLE statement: This chapters discussions of the RECEIVE_DATA, SEND_TABLE, SEND_DATA, SEND_MESSAGE, EXECUTE, END_EXECUTE, CONNECT, and DISCONNECT statements. The discussion of the ADD PROCEDURE metadata command in this manuals DML METADATA COMMANDS chapter The discussion of the %STATUS special variable in this manuals SPECIAL VARIABLES AND VALUE SYMBOLS chapter The discussion of the IAF Client/Server environment in the IAF User Guide and the IAF guide that applies to your operating system

6-290

Language Statements IAF 8.0 DML

RECEIVE_DATA

The discussion of the Data Definition Editors Procedures option in the IAF System Reference Manual.

Language Statements IAF 8.0 DML

6-291

RECEIVE_TABLE

RECEIVE_TABLE
Syntax
RECEIVE_TABLE [/HANDLE=connect_handle][/REPLACE] target_table_name & [FROM [database_handle.]source_table_name]

Category
Client/Server environment

Description
This statement enables a Client process to receive an entire table from a database that a given Server has invoked. Although this statement is intended primarily for use with virtual tables, it can also be used with physical tables. Note: If the Client and Server both have the same physical database invoked, care must be taken when using this statement with physical tables to ensure that the target table and the source table are NOT the same table. If the target table and the source table are the same table, this statement copies the table to itself. If the RECEIVE_TABLE statement specifies the /REPLACE qualifier, this results in the deletion of the table's data. When execution of the RECEIVE_TABLE statement takes place within a form, IAF places the operation's completion status in the %STATUS special variable.
target_table_name

This is the name of the table in which the Client is to receive the given source table's data.
database_handle

This is the handle of the database that holds the table whose data the Client process is to receive. It is necessary to include a database handle only if the Server has invoked multiple databases that may hold more than one table of the given name. If the RECEIVE_TABLE statement specifies no database handle, IAF uses the first occurrence of the given table that it finds.

6-292

Language Statements IAF 8.0 DML

RECEIVE_TABLE

source_table_name

This is the name of the table whose data the Client process is to receive. If the RECEIVE_TABLE statement specifies no source table, IAF uses the first occurrence of a table having the same name as the target table.

Qualifiers
The following qualifiers are valid for use with the RECEIVE_TABLE statement:
/HANDLE=connect_handle

Specifies the connection on which the RECEIVE_TABLE statement is to operate. The IAF Client searches its list of current connections. If the specified connect handle matches a current connection, the RECEIVE_TABLE statement operates on that connection. Otherwise, IAF returns an error status in the %STATUS special variable. Note that you can specify the connect handle via a constant or a variable. If the RECEIVE_TABLE statement does not include this qualifier, the default connect handle is the handle that the last previously executed CONNECT statement specified. If no connection exists, IAF displays an error message.
/REPLACE

This qualifier indicates that IAF is to empty the target table prior to copying the source table's data into it. If the RECEIVE_TABLE statement does not include this qualifier, IAF appends the source table's data to the target table.

Examples
RECEIVE_TABLE PARTS RECEIVE_TABLE EMPLOYEES FROM WESTERN_DIVISION.EMPLOYEES RECEIVE_TABLE /HANDLE=#LOOKUP /REPLACE ORDERS FROM AREA1_ORDERS

Related Topics
The following references contain information pertaining to the RECEIVE_TABLE statement:

Language Statements IAF 8.0 DML

6-293

RECEIVE_TABLE

This chapters discussions of the RECEIVE_DATA, SEND_TABLE, SEND_DATA, SEND_MESSAGE, EXECUTE, END_EXECUTE, CONNECT, and DISCONNECT statements. The discussion of the ADD PROCEDURE metadata command in this manual's DML METADATA COMMANDS chapter The discussion of the %STATUS special variable in this manuals SPECIAL VARIABLES AND VALUE SYMBOLS chapter The discussion of IAF's Client/Server environment in the IAF User Guide and the IAF guide that applies to your operating system The discussion of the Data Definition Editors Procedures option in the IAF System Reference Manual.

6-294

Language Statements IAF 8.0 DML

RELEASE

RELEASE
Syntax
RELEASE resource_name

Category
Inter-process communication

Description
This statement indicates that IAF is to disassociate the process that executes the statement from the specified resource. This means that the process that executes the RELEASE statement will no longer be able to receive messages from the given resource. Likewise, the process will no longer be able to send messages to the given resource. The SEND, RECEIVE and RELEASE DML statements are implemented on OpenVMS and UNIX platforms only. In order for these statements to properly execute on UNIX platforms, the gem_snrd daemon must be running at the time that the given statement is executed.
resource_name

This is the name of the resource from which IAF is to disassociate the process executing the RELEASE statement.

Example
RELEASE TOPAZ

Related Topics
The following references contain information pertaining to the RELEASE statement: This chapters discussions of the RECEIVE and SEND statements. The discussion of inter-process communication in the IAF Users Guide and the IAF guide that applies to your operating system.

Language Statements IAF 8.0 DML

6-295

REPORT

REPORT
Syntax
REPORT

Category
Utilities and program development

Description
This statement invokes IAFs Reporting Environment, which enables you to create, modify, run, and delete report definitions via a menu and window-driven interface. The Reporting Environment also enables you to display and print report listings created as a result of running report definitions. You can execute the REPORT statement from the IAF command line prompt (GEM> by default), or from within a DML application.

Related Topics
The following references contain information pertaining to the REPORT statement: The IAF Reporting Environment Reference Manual. The Guide to Using IAFs Reporting Environment for Windows.

6-296

Language Statements IAF 8.0 DML

REPOSITION

REPOSITION
Syntax
REPOSITION BY [-]nnn

or
REPOSITION TO nnn

Category
Miscellaneous

Description
This statement enables you to reset the line count in a report and control the position of the reports output. Note that execution of this statement must take place within the context of a REPORT form. The following table lists and describes the two syntax formats that are valid for this statement. Syntax REPOSITION BY []nnn Description This syntax allows you to increase or decrease a REPORT forms current line count by the given value (nnn). If a minus sign (-) precedes the value, IAF moves the reports current output position back the given number of lines. Otherwise, IAF moves the reports current output position forward the given number of lines. This syntax allows you to move a REPORT forms current output position to the absolute line position that the given value indicates. The specified value is relative to the beginning of the report.

REPOSITION TO nnn

Examples
REPOSITION BY -1

This example causes IAF to move the given reports current output position back one line.

Language Statements IAF 8.0 DML

6-297

REPOSITION

REPOSITION TO 10

This statement causes IAF to move the given reports current output position to line 10.
PROCEDURE_FORM COLUMNS_REPORT BEGIN_BLOCK INIT #COUNT=1 #COL=1 PERFORM MAIN END_BLOCK END_FORM REPORT_FORM MAIN /READ_ONLY /WIDTH=80 & /OUTPUT=PARTS_REPORT & /TABLE=PART_MASTER & /LHEADING=(MASK(!DD-!SM-!LY !HH:!MI, %REPORT_DATE)) & /RHEADING=(MASK(Page !-@@@@@, %PAGE)) BEGIN_BLOCK CHECK_COLUMNS IF (#COUNT=12) REPOSITION TO 6 #COL=45 END_IF END_BLOCK OUTPUT_BLOCK PART_CODE /COL=(#COL) & /SOURCE=(PART_MASTER(PART_CODE)) OUTPUT_BLOCK PART_DESCRIPTION /COL=(#COL+15) & /SOURCE=(PART_MASTER(PART_DESCRIPTION)) BEGIN_BLOCK INCREMENT #COUNT=#COUNT+1 END_BLOCK END_FORM

This example begins a new column of data starting on row 6 in column 45 of the report after printing 11 rows of data.

Related Topics
The following references contain information pertaining to the REPOSITION statement: The discussion of REPORT forms in this manuals Forms and Form Qualifiers chapter. The discussion of forms in the IAF Users Guide.

6-298

Language Statements IAF 8.0 DML

REWIND_TEXT

REWIND_TEXT
Syntax
REWIND_TEXT tag

Category
Text file management

Description
This statement causes IAF to make the beginning of the given text file the current record position.
tag

This is the handle for the text file to rewind, and is the handle that the OPEN_TEXT statement specified when opening the file.

Examples
REWIND_TEXT ADDRESS REWIND_TEXT PHONE

Related Topics
The following references contain information pertaining to the REWIND_TEXT statement: This chapters discussions of the OPEN_TEXT, CLOSE_TEXT, READ_LINE, WRITE, and WRITE_LINE statements.

Language Statements IAF 8.0 DML

6-299

ROLLBACK

ROLLBACK
Syntax
ROLLBACK

Category
Data access

Description
This statement rolls back all database changes made since the current transaction began (the database returns to the way it was before the transaction began), if the form that executes the ROLLBACK statement also started the transaction. The ROLLBACK statement completes the current transaction. Therefore, for every ROLLBACK statement, IAF must have implicitly or explicitly started a transaction within the same form. IAF implicitly starts a transaction upon encountering a form header statement that includes the /TABLE qualifier or the /REPEAT qualifier, or if no transaction is in progress, and you execute any DML statement that requires database access. An explicit transaction is a transaction that you begin by executing the START_TRANSACTION statement. If the current transaction is a pseudo transaction (i.e. a transaction started within a transaction), executing the ROLLBACK statement has no effect on the data, and the real transaction continues. However, executing the ROLLBACK statement causes IAF to terminate any record stream that a given transaction (pseudo or real) created. Note that when exiting a form, the transaction level is always the same as it was upon entering the form, regardless of whether additional transactions were started or rolled back within the form. When the ROLLBACK statement executes within a form, IAF places the operations completion status in the %STATUS special variable.

Related Topics
The following references contain information pertaining to the ROLLBACK statement:

6-300

Language Statements IAF 8.0 DML

ROLLBACK

This chapters discussions of the START_TRANSACTION, COMMIT, and CONTINUE statements. The discussion of forms and form qualifiers in this manuals Forms and Form Qualifiers chapter. The discussion of the %STATUS special variable in this manuals Special Variables And Value Symbols chapter. The discussion of transactions and transaction control in the IAF Users Guide.

Language Statements IAF 8.0 DML

6-301

RUN_TESTS

RUN_TESTS
Syntax
RUN_TESTS

Category
Miscellaneous

Description
RUN_TESTS compiles and runs all the DML tests in the current directory (folder), producing a report listing called TEST_RESULTS.LIS. RUN_TESTS redirects compiler messages, test output, runtime messages and DML stack traces to the report listing, TEST_RESULTS.LIS. The RUN_TESTS statement performs the following actions: Compiles all DML files in the current directory, producing corresponding DMC files. Processes all DMC files in the current directory and PERFORMs all the tests found in those files. Produces a test report, TEST_RESULTS.LIS The DMC files are assumed to contain one or more tests. A test is defined as a form with a name beginning with "TEST_", for example, TEST_1, TEST_2, etc. Each DMC file is processed in turn, and all the tests inside the DMC file are run (performed). Forms with names that do not start with TEST_ are ignored by RUN_TESTS. A DMC file can contain up to four special test forms that cause special processing, as follows: TEST_SETUP is performed before each test is run. It can be used to do common setup work for each test. TEST_TEARDOWN is performed after each test is run. It can be used to do common cleanup work after each test. TEST_FIXTURE_SETUP is performed once per DMC file, before any other form in the file. It can be used to do one-time setup.

6-302

Language Statements IAF 8.0 DML

RUN_TESTS

TEST_FIXTURE_TEARDOWN is performed once per DMC file, after all the other forms in the file. It can be used to do one-time final cleanup work.

Example 1
Assume a folder containing the following three files:
!FILE: MASK_TESTS.DML !Mask with a NULL string, uses the same length as mask. PROCEDURE_FORM TEST_MASK_1 #A = (MASK('!@@@@@@@@@@',"")) ASSERT(#A = " END_FORM !If DATA larger than MASK, returns all "%" chars with length of MASK. PROCEDURE_FORM TEST_MASK_2 #A = (MASK('!@@@@@@@@@@',"THISISALONGSTRING")) ASSERT(#A = "%%%%%%%%%%") END_FORM ")

!FILE: MISC_TESTS.DML PROCEDURE_FORM TEST_IF #A = 1 #B = 2 #C = 3 IF ((#A + #B) = #C) EXIT(%SUCCESS) END_IF ASSERT_FAIL /MSG="Simple If Test FAILED" END_FORM !FILE: STRING_TESTS.DML PROCEDURE_FORM TEST_CAT #A = "Hello" #B = "World" #C = #A & #B ASSERT_EQUAL ("HelloWorld") (#C) /MSG="concatenation failed" END_FORM PROCEDURE_FORM TEST_LEN

Language Statements IAF 8.0 DML

6-303

RUN_TESTS

#A = "Hello" ASSERT_EQUAL (5) (LEN(#A)) /MSG="LEN function failed" END_FORM

The TEST_RESULTS.LIS report created by RUN_TESTS follows:

DML Test Results ------ Build started -----Compiling: .\MASK_TESTS.DML ... Compiling: .\MISC_TESTS.DML ... Compiling: .\STRING_TESTS.DML ... ------ Execution started -----Running: c:\Ross\Soft\test73\demo\demo7\MASK_TESTS.DML Performing: TEST_MASK_1 Performing: TEST_MASK_2 Running: c:\Ross\Soft\test73\demo\demo7\MISC_TESTS.DML Performing: TEST_IF Running: c:\Ross\Soft\test73\demo\demo7\STRING_TESTS.DML Performing: TEST_CAT Performing: TEST_LEN ====== Result Summary ====== Build succeeded : 3 Build failed Tests passed Tests failed : 0 : 5 : 0

============================

Example 2
This example demonstrates the order in which the setup and teardown special tests are performed. Assume a folder containing the following file:
!FILE: DEMO_TESTS.DML PROCEDURE_FORM TEST_FIXTURE_SETUP PRINT "this is test_fixture_setup" END_FORM PROCEDURE_FORM TEST_FIXTURE_TEARDOWN PRINT "this is test_fixture_teardown" END_FORM PROCEDURE_FORM TEST_SETUP

6-304

Language Statements IAF 8.0 DML

RUN_TESTS

PRINT "this is test_setup" END_FORM PROCEDURE_FORM TEST_TEARDOWN PRINT "this is test_teardown" END_FORM PROCEDURE_FORM TEST_ONE PRINT "this is test one" END_FORM PROCEDURE_FORM TEST_TWO PRINT "this is test two" END_FORM

The TEST_RESULTS.LIS report created by RUN_TESTS follows:

DML Test Results

------ Build started -----Compiling: .\DEMO_TESTS.DML ...

------ Execution started -----Running: c:\Ross\Soft\test73\demo\demo3\DEMO_TESTS.DML Performing: TEST_FIXTURE_SETUP >>Value is /this is test_fixture_setup/ Performing: TEST_SETUP >>Value is /this is test_setup/ Performing: TEST_ONE >>Value is /this is test one/ Performing: TEST_TEARDOWN >>Value is /this is test_teardown/ Performing: TEST_SETUP >>Value is /this is test_setup/ Performing: TEST_TWO >>Value is /this is test two/ Performing: TEST_TEARDOWN >>Value is /this is test_teardown/ Performing: TEST_FIXTURE_TEARDOWN >>Value is /this is test_fixture_teardown/

Language Statements IAF 8.0 DML

6-305

RUN_TESTS

====== Result Summary ====== Build succeeded : 1 Build failed Tests passed Tests failed : 0 : 2 : 0

============================

Related Topics
The following references contain information pertaining to the ASSERT statement: This chapter's discussion of the ASSERT, ASSERT_EQUAL, ASSERT_FAIL and RUN_TESTS statements. The discussion of the special value symbol %ASSERT_FAILURE in the "Special Variables and Value Symbols" Chapter of this manual.

6-306

Language Statements IAF 8.0 DML

SEARCH

SEARCH
Syntax
SEARCH string

Category
Miscellaneous

Description
This statement enables you to search for a metadata entity whose name matches the given string. This statement operates on all databases to which you are attached and searches the Data Dictionary of each database. If IAF finds entities that match the search string, it displays the entities in the Database References Found window. IAF indicates the database in which the found metadata exists, and displays the names of the entities in groups of like metadata (i.e. all tables that match the search string, all fields that match the search string, etc.). If IAF does not find any entity that matches the search string, the Database References Found window indicates only the database(s) on which the SEARCH statement operated. When the SEARCH statement executes within a form, IAF places the operations completion status in the %STATUS special variable.
string

This is a string indicating the metadata for which IAF is to search. The string can include the wildcard characters * and %, where * represents zero or more unknown characters, and % represents a single unknown character. IAF searches for any metadata entities (e.g. datatypes, fields, tables, domains, triggers, indices) whose names match the specified string.

Examples
SEARCH SALES*

This example searches for metadata entities having names that start with the string SALES. Some examples of matching names are SALES, SALES_ITEM, SALES_ORDER, and SALES_GROUP.
SEARCH *OUNT*

Language Statements IAF 8.0 DML

6-307

SEARCH

This example searches for metadata entities having names that include the string EM. Some examples of matching names are ACCOUNTS, ACCOUNT_ID, and ITEM_COUNT,
SEARCH %EM*

This example searches for metadata entities having names that include the string EM optionally preceded by one character. Some examples of matching names are EMPLOYEES, MEMBERS, and TEMP_ID.

Related Topics
The following references contain information pertaining to the SEARCH statement: The discussion of the %STATUS special variable in this manuals Special Variables And Value Symbols chapter. The discussion of the Data Definition Editor in the IAF System Reference Manual and the IAF guide that applies to your database engine.

6-308

Language Statements IAF 8.0 DML

SEND

SEND
Syntax
SEND resource_name [/qualifiers] message_text

Category
Inter-process communication

Description
This statement enables a process to send text messages, which one or more other processes can receive via the RECEIVE statement. The number of processes that can receive the message depends upon the RECEIVE statements syntax. If the RECEIVE statement includes the /MAILBOX qualifier, no more than one process receives the message. Otherwise, multiple processes can receive the message. In either case, a process can receive a message only if the process executes a RECEIVE statement specifying the same resource that the SEND statement specifies. When execution of the SEND statement takes place within a form, IAF places a success status in the %STATUS special variable if the operation succeeds (i.e. a process is currently receiving via the resource that the SEND statement specified). Otherwise, IAF places a failure status in the %STATUS special variable. The SEND, RECEIVE and RELEASE DML statements are implemented on OpenVMS and UNIX platforms only. In order for these statements to properly execute on UNIX platforms, the gem_snrd daemon must be running at the time that the given statement is executed.
resource_name

This is either a constant or a variable indicating the name of the resource via which to send the given text message.
message_text

This is the message to send, and is a string having no more than 255 characters.

Language Statements IAF 8.0 DML

6-309

SEND

Qualifiers
The following qualifiers are valid for use with the SEND statement:
/CREATE

This qualifier indicates that if the mailbox that the given resource name indicates does not exist, IAF is to create it.
/GROUP

Specifying this qualifier in conjunction with the /CREATE qualifier indicates that IAF is to create a new mailbox and make the messages that the mailbox receives available to all members of the current group.
/MAILBOX

This qualifier indicates that the current process is to receive text via a mailbox device.
/SYSTEM

Specifying this qualifier in conjunction with the /CREATE qualifier indicates that IAF is to create a new mailbox and make the messages that the mailbox receives available to all members of the system.
/WAIT

This qualifier indicates that the sending process is to wait for a process to receive the message it is sending. If the SEND statement does not include this qualifier, IAF returns a failure status if no receiving process is currently using the same resource name as the given SEND statement.

Examples
SEND YELLOW Hello

This SEND statement sends the message Hello to any processes that are currently receiving via the resource named YELLOW.
#NAME=RED #MESSAGE=123 SEND #NAME #MESSAGE

This SEND statement sends the message 123 to any processes that are currently receiving via the resource named RED.
#NAME=RED SEND BLUE /MAILBOX (RETURN: & #NAME)

This SEND statement sends the message RETURN: RED to a single process that is currently receiving via the resource named BLUE.
6-310 Language Statements IAF 8.0 DML

SEND

Related Topics
The following references contain information pertaining to the SEND statement: This chapters discussions of the RECEIVE and RELEASE statements. The discussion of the %STATUS special variable in this manuals Special Variables and Value Symbols chapter. The discussion of inter-process communication in the IAF Users Guide and the IAF guide that applies to your operating system.

Language Statements IAF 8.0 DML

6-311

SEND_DATA

SEND_DATA
Syntax
SEND_DATA data_element[,data_element[,...]]

Category
Client/Server environment.

Description
This statement causes IAF to attempt to send row data from the currently executing stored procedure to a IAF Client receiving the row data via the RECEIVE_DATA statement. A stored procedure is typically a PROCEDURE form containing DML code that executes within the context of a stored procedure Server. A Client/Server connection must be established between the Client executing the RECEIVE_DATA statement and the Server executing the SEND_DATA statement in order for the Server to be able to send row data to the Client. The OPEN_APPLICATION and CONNECT statements enables a IAF Client to connect to a IAF stored procedure Server. Upon executing a SEND_DATA statement, IAF attempts to send the given row data to the Client operating on the given connection. If execution of a RECEIVE_DATA statement has not yet taken place on the connection, the SEND_DATA statement waits until this happens. When execution of a RECEIVE_DATA statement takes place on the connection, IAF sends the row data that the SEND_DATA statement specified. When execution of the SEND_DATA statement takes place within a form, IAF returns the SEND_DATA statement's execution status in the %STATUS special variable. The return status value can be one of the value symbols that the following table lists and describes.

Status Return Value %NORMAL

Description IAF successfully sent the given row data.

6-312

Language Statements IAF 8.0 DML

SEND_DATA

Status Return Value %EXIT

Description The client has prematurely terminated the stored procedure's execution (i.e. via an END_EXECUTE statement). The client has died, and the currently executing stored procedure is to terminate.

Any value other than %NORMAL or %EXIT

data_element[,data_element[,...]] This is one, or more, data elements comprising the row data that IAF is to send to the Client. Data elements can be variables, table fields, parameters, array elements, or expressions. The number of data element specifications that the SEND_DATA statement includes should be the same as the number of data elements specified for the given stored procedure.

Examples
SEND_DATA CUSTOMER(NAME),CUSTOMER(TELEPHONE) SEND_DATA #CUST_ID, #CUST_LIMIT

Related Topics
The following references contain information pertaining to the SEND_DATA statement: This chapter's discussions of the CONNECT, DISCONNECT, END_EXECUTE, EXECUTE, RECEIVE_DATA, RECEIVE_TABLE, SEND_MESSAGE, and SEND_TABLE statements. The discussion of the ADD PROCEDURE metadata command in this manual's DML Metadata Commands chapter The discussion of the %STATUS special variable in this manuals Special Variables and Value Symbols chapter. The discussion of the Data Definition Editors Procedures option in the IAF System Reference Manual. The discussion of the IAF Client/Server Environment in the IAF User Guide and the IAF guide that applies to your operating system.

Language Statements IAF 8.0 DML

6-313

SEND_MESSAGE

SEND_MESSAGE
Syntax
SEND_MESSAGE numeric_expression, text_expression

Category
Client/Server environment.

Description
This statement causes IAF to send a message from the currently executing stored procedure to a IAF Client. IAF displays the message in the Client's message area at the base of the screen. A stored procedure is typically a PROCEDURE form containing DML code that executes within the context of a stored procedure Server. A Client/Server connection must be established between the Client that is to receive the message and the Server that is executing the SEND_MESSAGE statement in order for IAF to be able to send the specified message text from the Server to the Client. The OPEN_APPLICATION and CONNECT statements enables a IAF Client to connect to a IAF stored procedure Server. IAF places no restrictions on when a Server can send a message to a Client. However, the SEND_MESSAGE statement is valid for use only within a stored procedure. You can use the SEND_MESSAGE statement to facilitate debugging and testing the stored procedure in which it operates. When execution of the SEND_MESSAGE statement takes place within a form, IAF returns the SEND_MESSAGE statement's execution status in the %STATUS special variable. The return status value can be one of the special symbols that the following table lists.

Status Return Values %NORMAL %EXIT

Description IAF successfully sent the given message text. The Client prematurely terminated the stored procedures execution via an END_EXECUTE statement.

6-314

Language Statements IAF 8.0 DML

SEND_MESSAGE

Status Return Values Any value other than %NORMAL or %EXIT

numeric_expression

Description The Client process died, and the currently executing stored procedure is to terminate.

This is a value indicating the severity of the given message. An odd number denotes an informational message. An even number denotes an error message, in which case, IAF's default behavior is to sound the system bell when displaying the message and wait for input from the Client user before continuing. This gives the Client user time to read the message before IAF overwrites it with a subsequent message. If the message is informational, IAF displays it without sounding the system bell or preventing subsequent messages from overwriting it.
text_expression

This is the text message that IAF is to display in the message area of the Client's screen. You can specify an expression indicating the message text by enclosing the expression in parentheses.

Examples
SEND_MESSAGE %NORMAL, ("On record " & #COUNT) SEND_MESSAGE %FAILURE, "Defined Method Unavailable - using default"

Related Topics
The following references contain information pertaining to the SEND_MESSAGE statement: This chapter's discussions of the ERROR, PRINT, CONNECT, DISCONNECT, EXECUTE, END_EXECUTE, RECEIVE_DATA, RECEIVE_TABLE, SEND_DATA, and SEND_TABLE statements. The discussion of the ADD PROCEDURE metadata command in this manuals DML Metadata Commands chapter The discussion of the %STATUS special variable in this manuals Special Variables and Value Symbols chapter.

Language Statements IAF 8.0 DML

6-315

SEND_MESSAGE

The discussion of the Data Definition Editor's Procedures option in the IAF System Reference Manual. The discussion of the IAF Client/Server Environment in the IAF User Guide and the IAF guide that applies to your operating system.

6-316

Language Statements IAF 8.0 DML

SEND_TABLE

SEND_TABLE
Syntax
SEND_TABLE [/HANDLE=connect_handle][/REPLACE] source_table_name [TO [database_handle.]target_table_name]

Category
Client/Server environment.

Description
This statement enables a Client process to send an entire table to a database to which a given Server is attached. Although this statement is intended primarily for use with virtual tables, it can also be used with physical tables. Note: If the Client and Server both have the same physical database invoked, care must be taken when using this statement with physical tables to ensure that the target table and the source table are the NOT the same table. If the target table and the source table are the same table, this statement copies the table to itself. If the SEND_TABLE statement specifies the /REPLACE qualifier, this results in the deletion of the table's data. When execution of the SEND_TABLE statement takes place within a form, IAF places the operation's completion status in the %STATUS special variable.
source_table_name

This is the name of the table to send.

database_handle

This is the handle of the database that holds the table that is to receive the data being sent. It is necessary to include a database handle only if the Server has invoked multiple databases that may hold more than one table of the given name. If the SEND_TABLE statement specifies no database handle, IAF uses the first occurrence of the given table that it finds.
target_table_name

Language Statements IAF 8.0 DML

6-317

SEND_TABLE

This the name of the table that is to receive the table data being sent.

Qualifiers
The following qualifiers are valid for use with the SEND_TABLE statement:
/HANDLE=connect_handle

Specifies the connection on which the SEND_TABLE statement is to operate. The IAF Client searches its list of current connections. If the specified connect handle matches a current connection, the SEND_TABLE statement operates on that connection. Otherwise, IAF returns an error status in the %STATUS special variable. Note that you can specify the connect handle via a constant or a variable. If the SEND_TABLE statement does not include this qualifier, the default connect handle is the handle that the last previously executed CONNECT statement specified. If no connection exists, IAF displays an error message.
/REPLACE

This qualifier indicates that IAF is to empty the target table prior to sending the source table's data to it. If the SEND_TABLE statement does not specify this qualifier, IAF appends the source table's data to the target table.

Examples
SEND_TABLE PARTS SEND_TABLE EMPLOYEES TO WESTERN_DIVISION.EMPLOYEES SEND_TABLE /HANDLE=#LOOKUP /REPLACE ORDERS TO AREA1_ORDERS

Related Topics
The following references contain information pertaining to the SEND_TABLE statement: This chapters discussions of the RECEIVE_DATA, RECEIVE_TABLE, SEND_DATA, SEND_MESSAGE, EXECUTE, END_EXECUTE, CONNECT, and DISCONNECT statements. The discussion of the ADD PROCEDURE metadata command in this manuals DML Metadata Commands chapter.

6-318

Language Statements IAF 8.0 DML

SEND_TABLE

The discussion of the %STATUS special variable in this manuals Special Variables and Value Symbols chapter. The discussion of the IAF Client/Server Environment in the IAF User Guide and the IAF guide that applies to your operating system. The discussion of the Data Definition Editors PROCEDURES option in the IAF System Reference Manual.

Language Statements IAF 8.0 DML

6-319

SET ACCESS

SET ACCESS
Syntax
SET ACCESS table_name [access_mode] [/SHARE=share_mode]

or
SET ACCESS table_name /RMS_OPTIONS=rms_option[,rms_option[,...]]

Category
System settings

Description
This statement enables you to control the way IAF opens an unrelated table file, and/or the way a DML program subsequently accesses the tables (real and virtual) within a database. You must execute this statement outside the context of a transaction. You can execute this statement multiple times to change a given processs access mode.

Note:
This statements effect applies only to the RMS engine. See the Guide to Using IAF with RMS for details.
access_mode

This is the mode in which the current process can access the specified table. The following table lists and describes the access modes that are valid for use with the SET ACCESS statement. Access Mode WRITE MODIFY Description This access mode allows the process to add new records and/or read the current record. This access mode allows the process to read, update, or delete the current record and/or create new records. This is the default setting. This access mode allows the process the same access as WRITE access mode, but indicates that new records are to be added to the end of the table.

APPEND

6-320

Language Statements IAF 8.0 DML

SET ACCESS

Access Mode READ

Description This access mode allows the process read-only access to the table.

share_mode

This is the mode in which other processes can access the specified table. The table on the following page lists and describes the share modes that are valid for use with the SET ACCESS statement. Share Mode WRITE MODIFY READ NONE Description This share mode allows other processes to add new records and/or read existing records. This share mode prevents other processes from adding new records to the table. This is the default setting. This share mode allows other processes read-only access to the table. This share mode allows no other processes access to the table, and is equivalent to an exclusive lock on the table.

Note that a given end users security access to a table always overrides any SET ACCESS command. Whether IAF attempts to execute the SET ACCESS statement immediately or at the start of the next transaction, depends upon the database engine in use. If IAF attempts to execute the SET ACCESS statement immediately and the execution of the statement is successful within a form, the value of the %STATUS system variable is %NORMAL. If IAF attempts to execute the SET ACCESS statement immediately, and execution of the statement is not successful (due to the conflicting requirements of other processes accessing the same table), the value of the %STATUS system variable is a value other than %NORMAL. If IAF is to execute the statement at the start of a transaction, the process waits until it can obtain the correct access mode necessary to ensure a successful execution.

Language Statements IAF 8.0 DML

6-321

SET ACCESS

Qualifiers
The following qualifiers are valid for use with the SET ACCESS statement:
/RMS_OPTIONS=rms_option[,rms_option[,...]]

This qualifier facilitates setting RMS performance options when running IAF with RMS. Specifically, the /RMS_OPTIONS qualifier can specify one or more of the following options:
DEFERRED_WRITESSEQUENTIAL_ONLY READ_AHEADWRITE_BEHIND READ_CHECKWRITE_CHECK

For details regarding these options, refer to your OpenVMS Record Management Services documentation. In addition to the RMS performance options listed above, the options that the following table lists and describes are also valid for use with the /RMS_OPTIONS qualifier. Option REOPEN_FILE Description This option causes IAF to close the specified tables file and re-open it. This is useful if a process needs to access the latest version of the file (e.g. one that has been modified by an external process while IAF had the file open). This option turns off all RMS options listed in the first group above.

STANDARD

The /RMS_OPTIONS qualifier is valid for use only when running IAF with the RMS database engine, and can be used inside or outside a transaction, unless RMS Journaling is enabled for the table in use. If RMS Journaling is enabled, the qualifier is valid for use only outside a transaction.

6-322

Language Statements IAF 8.0 DML

SET ACCESS

/SHARE=share_mode

This qualifier enables you to specify the mode in which other processes can access the specified table. Valid share modes are WRITE, MODIFY, READ, and NONE. For details regarding these share modes, refer to the share mode table on the preceding page.
Examples SET ACCESS MEMBERS APPEND /SHARE=READ SET ACCESS MOVIES /RMS_OPTIONS=REOPEN_FILE,SEQUENTIAL_ONLY

Related Topics
The following references contain information pertaining to the SET ACCESS statement: The discussion of the %STATUS special variable in this manuals SPECIAL VARIABLES AND VALUE SYMBOLS chapter. The discussion of the SET ACCESS statement in the IAF guide that applies to your database engine.

Language Statements IAF 8.0 DML

6-323

SET BROADCAST

SET BROADCAST
Syntax
SET BROADCAST broadcast_categories

Category
Miscellaneous

Description
This statement is used to enable or disable broadcast message categories for thin client and character cell users on the OpenVMS platform. The broadcast_catagories parameter can also be a variable. Special the broadcast categories as a comma separated list containing any combination of the following: ALL, DCL, GENERAL, MAIL, NOALL, NODCL, NOGENERAL, NOMAIL, NONE, NOOPCOM, NOPHONE, NOQUEUE, NOSHUTDOWN, NOURGENT, NOUSER1, NOUSER2, NOUSER3, NOUSER4, NOUSER5, NOUSER6, NOUSER7, NOUSER8, NOUSER9, NOUSER10, NOUSER11, NOUSER12, NOUSER13, NOUSER14, NOUSER15, NOUSER16, OPCOM, PHONE, QUEUE, SHUTDOWN, URGENT, USER1, USER2, USER3, USER4, USER5, USER6, USER7, USER8, USER9, USER10, USER11, USER12, USER13, USER14, USER15, USER16

6-324

Language Statements IAF 8.0 DML

SET CAT_FILTER

SET CAT_FILTER
Syntax
SET CAT_FILTER

Category
Data access

Description
This command sets a string_expression (table name) to a special variable %CAT_FILTER. The table name will be associated with the virtual table GEM_CAT_RELATION_FIELDS_FILTER, whose description is detailed below: GEM_CAT_RELATION_FIELDS_FILTER is a virtual table with the same structure of GEM_CAT_RELATION_FIELDS. The only difference is that instead of retrieving all columns of all tables, it only retrieves columns associated to a table contained in the special variable %CAT_FILTER. If this variable contains a null value or a value of an invalid table name, the virtual table will be empty

Language Statements IAF 8.0 DML

6-325

SET DATABASE

SET DATABASE
Syntax
SET [/LOCAL] DATABASE database_handle

Category
System settings

Description
This statement enables you to specify the current default database (i.e. the database to which IAF assumes table field references apply). By default, this statement sets the default database globally, and if no database has been set locally, the specified database handle is the default database handle.
database_handle

This is the handle of the database that is to be the default database. If the handle is the reserved word VIRTUAL, which is valid only for virtual databases, and there is no virtual database having VIRTUAL as its handle, IAF creates one.

Qualifier
The following qualifier is valid for use with the SET DATABASE statement:
/LOCAL

This qualifier indicates that IAF is to set the default database locally. A locally set database is active for the form in which it is set and all forms which that form calls until one of the following events occur: The form subsequently executes a SET /LOCAL DATABASE or SET DATABASE statement. The form calls a form that executes a SET DATABASE statement.

Note that when using the /LOCAL qualifier in a NORMAL form, the first display is not aware of the statement. Therefore, the form calling the NORMAL form should set the default database.
6-326 Language Statements IAF 8.0 DML

SET DATABASE

Examples
SET DATABASE GL SET/LOCAL DATABASE INVENTORY

Related Topics
The following references contain information pertaining to the SET DATABASE statement: This chapters discussions of the INVOKE and SHOW DATABASE statements. The discussion of the GEM_DATABASE_n System Customization Variable in the IAF guide that applies to your operating system. The discussion of virtual databases in the IAF Users Guide.

Language Statements IAF 8.0 DML

6-327

SET DATE_FORMAT

SET DATE_FORMAT
Syntax
SET DATE_FORMAT format_name

Category
System settings

Description
In addition to allowing you to enter dates in the standard format, DDMon-YYYY, IAF allows you to specify an optional date input format via the SET DATE_FORMAT statement. Date inputs take place in the given format, and IAF then converts them to the standard format prior to redisplaying and storing them. format_name This is the name of the date format to use. Valid date format names are as follows:
DDMMYY MMDDYY YYMMDD MMDDYYYY DDMMYYYY YYYYMMDD

DDMMYY is the default date format if you do not explicitly set a format via the SET DATE_FORMAT statement.

Examples
SET DATE_FORMAT MMDDYY SET DATE_FORMAT YYMMDD

Related Topics
The following references contain information pertaining to the SET DATE_FORMAT statement:

6-328

Language Statements IAF 8.0 DML

SET DATE_FORMAT

This chapters discussion of the SHOW DATE_FORMAT statement. The discussion of dates in the IAF Users Guide.

Language Statements IAF 8.0 DML

6-329

SET DEFAULT

SET DEFAULT
Syntax
SET DEFAULT directory

Category Miscellaneous Description This statement sets the users default directory (aka current working directory). See also the CD and SET WD statements.

6-330

Language Statements IAF 8.0 DML

SET ENTRY_MENU

SET ENTRY_MENU
Syntax
SET ENTRY_MENU [database_handle.][system_name:]facility_name

or
SET ENTRY_MENU

Category
System settings

Description
This statement enables you to specify the name of a menu that IAF is to automatically execute at IAF start-up time, or disable automatic menu execution. Use the first syntax above to set a default menu, and the second syntax above to disable automatic execution. If you use the SET ENTRY_MENU statement to specify a default menu, IAF also executes the specified menu if you press the GM_INTERRUPT key from within IAF when no other interrupt action has been explicitly specified.
database_handle

This is the handle for the database in which the specified facility exists. It is necessary to include a database handle only if you have invoked multiple databases, and the given facility does not exist in the current default database.
system_name

This is the name of the system in which the specified facility resides. If you do not specify a system name, IAF assumes that the specified facility resides in the current default system.
facility_name

This is the name of the facility with which the menu to automatically execute is associated.

Language Statements IAF 8.0 DML

6-331

SET ENTRY_MENU

Examples
SET ENTRY_MENU ACCOUNTS_PAYABLE:MAIN_MENU SET ENTRY_MENU DATA_ENTRY

Related Topics
The following references contain information pertaining to the SET ENTRY_MENU statement: This chapters discussions of the SET SYSTEM, SET INTERRUPT, and SHOW ENTRY_MENU statements. The discussion of the System Definition Editor in the IAF System Reference Manual.

6-332

Language Statements IAF 8.0 DML

SET GLOBAL EXIT FORM

SET GLOBAL EXIT FORM

Syntax
SET /GLOBAL EXIT FORM FILENAME FORMNAME(P1, Pn) SET /GLOBAL EXIT FORM /FACILITY DB:SYS:FAC(P1, Pn)

Category
System settings

Description
The SET /GLOBAL EXIT FORM statement has the same syntax as the PERFORM statement except that the only additional qualifier that is permitted is /FACILITY. As with the PERFORM/FACILITY statement, the facility can of course be contained in a variable or expression. See the PERFORM statement documentation for further syntax information. At run-time, the SET /GLOBAL EXIT FORM statement establishes a global exit handler form that remains enabled until explicitly disabled with the SET /GLOBAL EXIT OFF statement. When enabled, the global exit handler form will be performed with the specified parameters (as they existed at the time the SET /GLOBAL EXIT FORM statement was executed) whenever IAF exits (subject to both the known and as yet unknown restrictions). Only one form can be the current global exit handler form. Subsequently executed SET /GLOBAL EXIT FORM statements override prior ones. The global exit handler form is performed after all local exit hander forms have been performed. The SET statement assumes /GLOBAL if neither /GLOBAL nor /LOCAL are specified. The SET EXIT FORM statement is invalid when called from within an executing exit handler form. In this situation no error diagnostic is generated at compile time because it is not possible for the compiler to know for certain at compile time that a form will become an active exit handler form. This statement returns an error at run-time when executed from within an active exit handler form (one that was called as a result of a IAF exit). The %EXIT_ACTIVE special variable can be used to determine if a form is currently executing as an exit handler.

Language Statements IAF 8.0 DML

6-333

SET GLOBAL EXIT FORM

Filename is a required form file name. This can be a variable or expression, but it cant be a subscripted array element variable. A nonblank filename is required for SET /GLOBAL EXIT FORM statement. Formname is a required form name. P1 through Pn are optional parameters. These parameters are evaluated at the time the SET /GLOBAL EXIT FORM statement is executed, their current contents are saved, then these saved values are later passed to the exit handler form when and if it is called. Any modifications made to exit handler form arguments made while an exit handler form is executing are discarded when the exit handler form exits. The state of the program when the exit handler form is entered is the state the program was in at the time the unexpected exit occurred except that all active transactions have been rolled back and the transaction level is zero. When exit handler form processing ends, DML execution ends and IAF exits. DML forms on the DML procedure call stack do not resume execution. While an exit handler form is executing, any attempt to perform user interface input returns GM_EXIT and any attempt to perform user interface output is ignored. Exit forms are performed when IAF is exited while a DML program is running, and correspondingly are not performed when exiting and a DML program is not running. Exit forms are also not performed when a machine crashes, a job is killed, a process is deleted, an image exit is forced, or when a fatal bug check occurs. Specific examples: A thin client user disconnects while a DML program is running and the thin server can detect the disconnection. This also includes clicking the red X to close the thin client window. A user exits a GCW Pro window while a DML program is running. This also includes clicking the red X to close the GCWPro window. The client is disconnected from iBrowser and reconnection fails. Additionally: There can be only one global exit form. The global exit form stays enabled until it is explicitly disabled.

6-334

Language Statements IAF 8.0 DML

SET GLOBAL EXIT FORM

The global exit form is performed after all local exit forms have been executed.

Related Topics
See also the SET /LOCAL EXIT FORM, SET /LOCAL EXIT OFF, SET /GLOBAL EXIT OFF and SHOW EXIT FORM statements as well as the %EXIT_FORM_ENABLED, %EXIT_FORM_ACTIVE, %EXIT_FORM_FILENAME and %EXIT_FORM_FORMNAME special variables.

Language Statements IAF 8.0 DML

6-335

SET GLOBAL EXIT OFF

SET GLOBAL EXIT OFF

Syntax
SET /GLOBAL EXIT OFF

Category
System settings

Description
This statement disables the global exit handler form, if any. It is not an error to disable a global exit handler form that was never enabled in the first place. If a DML program which has previously enabled a global exit handler form does not desire to have the global exit handler form called during an unexpected IAF exit, then it should explicitly disable the global exit handler form. The SET statement assumes /GLOBAL if neither /GLOBAL nor /LOCAL are specified.

Related Topics
See also the SET /GLOBAL EXIT FORM, SET /LOCAL EXIT FORM, SET /LOCAL EXIT OFF and SHOW EXIT FORM statements as well as the %EXIT_FORM_ENABLED, %EXIT_FORM_ACTIVE, %EXIT_FORM_FILENAME and %EXIT_FORM_FORMNAME special variables.

6-336

Language Statements IAF 8.0 DML

SET HELP OFF

SET HELP OFF

Syntax
SET HELP OFF

Category
System settings

Description
This statement disables the display of help text at the bottom of the screen.

Related Topics
The following references contain information pertaining to the SET HELP OFF statement: This chapters discussions of the SET HELP ON and SHOW HELP statements.

Language Statements IAF 8.0 DML

6-337

SET HELP ON

SET HELP ON
Syntax
SET HELP ON

Category
System settings

Description
This statement indicates that IAF is to display a single, dynamic line of help text at the bottom of the screen. If the end users current location is a table field input, the help text that IAF displays is the description given for the table field in the Data Dictionary. Otherwise, the help text describes the options and logical steps that are available to the end user from the current point within IAF. IAF continues to display dynamic help text at the bottom of the screen until execution of the SET HELP OFF statement takes place.

Related Topics
The following references contain information pertaining to the SET HELP ON statement: This chapters discussions of the SET HELP OFF and SHOW HELP statements.

6-338

Language Statements IAF 8.0 DML

SET ICON_NAME

SET ICON_NAME
Syntax
SET ICON_NAME string_expression

Category
System settings

Description
This statement enables you to specify the text that is to appear below the IAF icon when running IAF in an environment that supports a graphical user interface.
string_expression

This is a string expression indicating the text that is to appear below the IAF icon.

Examples
SET ICON_NAME GCW SET TITLE_BAR GEM: Motif

Related Topics
The following references contain information pertaining to the SET ICON_NAME statement: The Guide to Using IAF Client for Windows and the Guide to Using IAF Client for Windows Pro.

Language Statements IAF 8.0 DML

6-339

SET INPUT BACKGROUND

SET INPUT BACKGROUND

Syntax
SET INPUT BACKGROUND attribute[,attribute[,...]]

Category
System settings

Description
This statement allows you to specify the display attributes to use for screen output areas (these include input areas after input is done).
attribute[,attribute[,...]]

This is one or more of the attributes that the following table lists and describes. Attribute BOLD REVERSE BLINK UNDERLIN E NONE Description Display all characters bold. Display all characters in reverse video. Display all characters blinking. Display all characters underlined. Use no special attributes at all.

The default input background attribute is REVERSE.

Example
SET INPUT BACKGROUND BOLD,REVERSE

Related Topics
The following reference contains information pertaining to the SET INPUT BACKGROUND statement: The discussion of screen facilities in the IAF System Reference Manual.

6-340

Language Statements IAF 8.0 DML

SET INPUT FOREGROUND

SET INPUT FOREGROUND

Set Syntax
SET INPUT FOREGROUND attribute[,attribute[,...]]

Category
System settings

Description
This statement allows you to specify the display attributes to use for screen input areas.
attribute[,attribute[,...]]

This is one or more of the attributes that the following table lists and describes. Attribute BOLD REVERSE BLINK UNDERLIN E NONE Description Displays all characters bold. Displays all characters in reverse video. Displays all characters blinking. Displays all characters underlined. Uses no special attributes at all.

The default input foreground attributes are BOLD and REVERSE.

Example
SET INPUT FOREGROUND UNDERLINE

Related Topics
The following reference contains information pertaining to the SET INPUT FOREGROUND statement: The discussion of screen facilities in the IAF System Reference Manual.

Language Statements IAF 8.0 DML

6-341

SET INTERRUPT

SET INTERRUPT
Syntax
SET INTERRUPT dml_statement_expression

Category
System settings

Description
This statement enables you to specify a DML statement that IAF is to execute whenever an end user presses the GM_INTERRUPT key, or specify that IAF is to start a new IAF session whenever an end user presses the GM_INTERRUPT key.
dml_statement_expression

This is either an expression indicating a DML statement that IAF is to execute whenever an end user presses the GM_INTERRUPT key, or a blank expression (i.e. ). If the SET INTERRUPT statement specifies a blank expression, and the end user presses the GM_INTERRUPT key, IAF begins a new session, and places the end user at the previous sessions entry point within the context of the new session. For example, if your initial entry point into IAF was its command line prompt (GEM> by default), pressing the GM_INTERRUPT key places you in a new session at the IAF command line prompt for that session (GEM_1> by default to reflect the session level). However, if your initial entry point into IAF was a menu (due to a SET ENTRY_MENU statement in your IAF start-up file), pressing the GM_INTERRUPT key places you in a new session at the specified entry menu.

Examples
SET INTERRUPT PERFORM CUSTOMER_INQUIRY SET INTERRUPT PERFORM LIB:SHOW_TIME SET INTERRUPT

Related Topics
The following references contain information pertaining to the SET INTERRUPT statement: This chapters discussion of the SHOW INTERRUPT statement.
6-342 Language Statements IAF 8.0 DML

SET INTERRUPT

The discussion of key facilities in the IAF Conventions Guide. The discussion of IAF start-up files in the IAF guide that applies to your operating system.

Language Statements IAF 8.0 DML

6-343

SET KEY

SET KEY
Set Syntax
SET KEY physical_key_name [/qualifiers] logical_key_name

Category
System settings

Description
This statement enables you to assign a physical key on your keyboard to a logical key name within IAF. All user-supplied components of this statements syntax must be in uppercase letters. Note that IAF supplies a complete set of default key definitions that are adequate for most purposes.
physical_key_name

This is the name of the physical key on the keyboard. It must come from IAFs list of valid physical key names. For a complete list of valid physical key names, refer to the IAF Conventions Guide.

6-344

Language Statements IAF 8.0 DML

SET KEY

logical_key_name

This is the logical key name to which to assign the physical key. The logical key name indicates the logical function that IAF is to perform when an end user uses the given key or key sequence, and must come from IAFs list of valid logical key names. For a complete list of valid logical key names, refer to the IAF Conventions Guide. Note that there are no restrictions against mapping more than one physical key or key sequence to the same IAF logical function.

Qualifiers
The following qualifiers are valid for use with the SET KEY statement:
/EDIT

This qualifier indicates that the key definition applies to inputs that are part of an editing interface such as the form editing interface in the Forms Editor.
/GOLD

This qualifier indicates that the physical key sequence that will perform the given IAF function consists of the GM_GOLD key followed by the specified physical key.

Examples
SET KEY Z/GOLD GM_EXIT

This example maps the physical key sequence, GOLD/Z, to the logical key function, GM_EXIT.
SET KEY B/GOLD GM_USER9

This example maps the physical key sequence, GOLD/B, to the userdefined logical key function, GM_USER9.
SET KEY PF2 GM_HELP

This example maps the physical key, PF2, to the logical key function, GM_HELP.
SET KEY PF3 GM_INVALID

This example demonstrates how you can use the SET KEY statement to disable a physical key. Specifically, this example disables the physical key, PF3.

Language Statements IAF 8.0 DML

6-345

SET KEY

Related Topics
The following reference contains information pertaining to the SET KEY statement: The IAF Conventions Guide.

6-346

Language Statements IAF 8.0 DML

SET KEYBOARD

SET KEYBOARD
Syntax
SET KEYBOARD filename

Category
System settings

Description
This statement enables you to specify the name of the file that contains the keyboard definitions that IAF is to use.
filename

This is the name of the keyboard definition file that IAF is to use.

Example
SET KEYBOARD my_keydefs.keydefs

Related Topics
The following references contain information pertaining to the SET KEYBOARD statement: This chapters discussion of the SHOW KEYBOARD statement. The discussion of keyboard definition files in the IAF Conventions Guide.

Language Statements IAF 8.0 DML

6-347

SET /LOCAL EXIT FORM

SET /LOCAL EXIT FORM

Syntax
SET [/LOCAL] EXIT FORM FILENAME FORMNAME(P1, Pn) SET [/LOCAL] EXIT FORM FORMNAME(P1, Pn) SET [/LOCAL] EXIT FORM /FACILITY DB:SYS:FAC(P1, Pn)

Category
System settings

Description
The SET /LOCAL EXIT FORM statement has the same syntax as the PERFORM statement except that the only additional qualifier that is permitted is /FACILITY. As with the PERFORM/FACILITY statement, the facility can of course be contained in a variable or expression. See the PERFORM statement documentation for further syntax information. At run-time, the SET /LOCAL EXIT FORM statement establishes a local exit handler form for the life of the form from which it is set. When enabled, the local exit handler form will be performed with the specified parameters (as they existed at the time the SET /LOCAL EXIT FORM statement was executed) whenever IAF exits (subject to both the known and as yet unknown restrictions). The exit handler form set from within the current form (if any) is automatically disabled when the current form exits. Only one exit handler can be the current exit handler for the form. Subsequently executed Set Exit Form /Local statements override prior ones. The local exit handler forms are associated with the form within which they are enabled and are stacked in the same manner as forms are stacked. When IAF exits unexpectedly, and all currently established local exit handler forms are performed in reverse order (most recent first). No local exit handler form can be established for the DML prompt. The SET /LOCAL EIT FORM statement returns an error when executed at the DML prompt. The SET statement assumes /GLOBAL if neither /GLOBAL nor /LOCAL are specified.

6-348

Language Statements IAF 8.0 DML

SET /LOCAL EXIT FORM

The SET /LOCAL EXIT FORM statement is invalid when called from within an executing exit handler form. In this situation no error diagnostic is generated at compile time because it is not possible for the compiler to know for certain at compile time that a form will become an active exit handler form. This statement returns an error at run-time when executed from within an active exit handler form (one that was called as a result of a IAF exit). The %EXIT_ACTIVE special variable can be used to determine if a form is currently executing as an exit handler. Filename is an optional form file name. This can be a variable or expression, but it cant be a subscripted array element variable. If blank or missing, the name of the currently executing form file is used. A nonblank filename is required if the program which executes this statement was performed using the PERFORM/ARRAY statement. Formname is a required form name. P1 through Pn are optional parameters. These parameters are evaluated at the time the SET /LOCAL EXIT FORM statement is executed, their current contents are saved, then these saved values are later passed to the exit handler form when and if it is called. Any modifications made to exit handler form arguments made while an exit handler form is executing are discarded when the exit handler form exits. If a local exit handler form is enabled without specifying a form filename, then global variables within form file (compilation unit) scope with their state as they existed at the time the unexpected exit occurred will also be available to the exit handler form while it is executing. The local exit handler form can even modify global variables. Such modifications may later be seen by other subsequently executed local exit handler forms that exist within the same form file. The state of the program when the exit handler form is entered is the state the program was in at the time the unexpected exit occurred except that all active transactions have been rolled back and the transaction level is zero. When exit handler form processing ends, DML execution ends and IAF exits. DML forms on the DML procedure call stack do not resume execution. While an exit handler form is executing, any attempt to perform user interface input returns GM_EXIT and any attempt to perform user interface output is ignored.

Language Statements IAF 8.0 DML

6-349

SET /LOCAL EXIT FORM

Properties of Local Exit Forms

Each form can have its own local exit form. Local exit forms are automatically disabled when teh form from which they were enabled exits. Local exit forms are performed in last in, first out (LIFO) order.

Related Topics
See also the SET /GLOBAL EXIT FORM, SET /LOCAL EXIT OFF, SET /GLOBAL EXIT OFF and SHOW EXIT FORM statements as well as the %EXIT_FORM_ENABLED, %EXIT_FORM_ACTIVE, %EXIT_FORM_FILENAME and %EXIT_FORM_FORMNAME special variables.

6-350

Language Statements IAF 8.0 DML

SET LOCAL EXIT OFF

SET LOCAL EXIT OFF

Syntax
SET /LOCAL EXIT OFF

Category
System settings

Description
This statement disables the local exit handler form, if any, associated with the currently executing form. It is not an error to disable a local exit handler form that was never enabled in the first place. The SET statement assumes /GLOBAL if neither /GLOBAL nor /LOCAL are specified.

Related Topics
See also the SET /GLOBAL EXIT FORM, SET /LOCAL EXIT FORM, SET /GLOBAL EXIT OFF and SHOW EXIT FORM statements as well as the %EXIT_FORM_ENABLED, %EXIT_FORM_ACTIVE, %EXIT_FORM_FILENAME and %EXIT_FORM_FORMNAME special variables.

Language Statements IAF 8.0 DML

6-351

SET LOCK

SET LOCK
Syntax
SET LOCK option_keyword[,option_keyword[,...]]

Category
System settings

Description
This statement provides user control over locking strategies and is intended for use in multiple-user environments in which data contention problems are prevalent. Exercise caution when using this statement because it can produce an unrepeatable read situation (i.e. the data you read has been altered in the database, thereby rendering the data you read obsolete). Note that this statements options have no effect in a READ_ONLY transaction environment (i.e. they are applicable only in a READ_WRITE transaction). Also note that the SET LOCK statement affects only the current default database (it does not affect other attached databases). When execution of the SET_LOCK statement takes place within a form, IAF places the operations completion status in the %STATUS special variable.

6-352

Language Statements IAF 8.0 DML

SET LOCK

Option Keywords
The following table lists and describes the option keywords that are valid for use with the SET LOCK statement. Option Keyword DEFAULT=keyword Description The DEFAULT option enables you to specify a keyword indicating the default lock that IAF is to apply to data that it fetches on a stream if no explicit lock option was specified for the stream via a /LOCK qualifier on the statement that started the stream. The keyword that you specify via the DEFAULT option must be one of the following: NONE This keyword causes IAF to apply the equivalent of a /LOCK=NONE qualifier to streams for which no lock was explicitly specified. WRITE This keyword causes IAF to apply the equivalent a /LOCK=WRITE to streams for which no lock was explicitly specified. Note that because IAF does not allow updates on multipletable views, IAF does not apply write locks to multiple-table views. ENGINE_DEFINED This keyword indicates that the default lock to apply to streams for which no lock was explicitly specified is to be determined by the database engine in use. It is the same as the default that applies when first attaching to a database, and varies from engine to engine.

Language Statements IAF 8.0 DML

6-353

SET LOCK

Option Keyword DOMAIN_DEFAULT=key word

Description The DOMAIN_DEFAULT option enables you to specify the default domain lock that IAF is to use if no explicit domain lock has been specified via the /OPTIONS block qualifier or the CHECK_DOMAIN statements /OPTION qualifier. The keyword that you specify via the DOMAIN_DEFAULT option must be one of the following: NONE This keyword causes IAF to apply no lock to records selected via domains for which no lock was explicitly specified. WRITE This keyword causes IAF to apply a write lock to records selected via domains for which no lock was explicitly specified. ENGINE_DEFINED This keyword indicates that the default lock to apply to records selected via domains for which no lock was explicitly specified is to be determined by the database engine in use. If the default domain lock mode is not explicitly specified, it is the same as the default lock mode (i.e. for streams). If no default lock mode has been specified either, the default domain lock mode is engine defined.

FULL

This is IAFs default lock mode. In this mode, all data that IAF accesses receives a read lock so that no other process may update the data during the life of the transaction. This causes all reads to be repeatable. In this mode, IAF attempts to leave index blocks unlocked if possible. The data that IAF accesses still receives read locks. However, because the index structures are not locked, it is possible for a record not to exist at the start of a transaction, but then to exist later in the transaction.

NO_INDEX

6-354

Language Statements IAF 8.0 DML

SET LOCK

Option Keyword READ_ONLY_LOV

Description In this mode, IAF processes all list of values functionality (including table searches) in a read only transaction. Only the selected record receives a read lock. Note that specifying this lock mode normally causes IAF to place a read lock on the record associated with an item selected from a list of values. However, you can override this read lock at the input block level with a stream lock by appending the /OPTIONS=DOMAIN_LOCK_NONE qualifier to the given block statement. This causes IAF to place no lock on the record associated with an item selected from the given input blocks list of values.

TED_LINE

In this mode, IAF starts and ends a transaction for each operation that is performed on a table edit. For example, operations such as inserting a new line, modifying a line, and paging the data forward and backward all have their own transaction start and end (rollback or commit). Note that this mode works only if the transaction level is zero upon entering a given TABLE_FORM.

Examples
SET LOCK FULL SET LOCK READ_ONLY_LOV SET LOCK NO_INDEX,TED_LINE,READ_ONLY_LOV,DEFAULT=WRITE,DOMAIN_DEFAULT=NO NE

Related Topic
The following references contain information pertaining to the SET LOCK statement: This chapters discussion of the SHOW LOCK statement. The discussion of the %STATUS special variable in this manuals Special Variables and Value Symbols chapter.

Language Statements IAF 8.0 DML

6-355

SET LOCK

The discussions of transactions and multiple-user environments in the IAF Users Guide. The discussion of locking strategies in the IAF guide that applies to your database engine.

6-356

Language Statements IAF 8.0 DML

SET LOCK_TIMEOUT

SET LOCK_TIMEOUT
Syntax
SET LOCK_TIMEOUT seconds

Category
System settings

Description
This statement enables you to specify the number of seconds that IAF is to wait for a response at an input block of any kind before timing out, and is applicable only when an end user has a current read-write transaction on the database. If the given number of seconds pass, IAF handles the timeout as if the end user pressed the GM_EXIT key. If there are no transactions outstanding, or the transaction is a read- only transaction, the SET LOCK_TIMEOUT statement has no effect. If both a SET TIMEOUT value and a SET LOCK_TIMEOUT value are specified, IAF uses the LOCK_TIMEOUT value while a read-write transaction exists and the TIMEOUT value otherwise.
seconds

This is the number of seconds that IAF is to wait for a response at an input block of any kind before timing out when an end user has a current readwrite transaction on the database.

iBrowser-specific Behavior
Starting with V7.0.0B SP1, SET TIME_OUT and SET LOCK_TIMEOUT have been implemented utilizing iBrowsers heartbeat. The heartbeat occurs in multiples of 2 minutes at which time it will check to see if the TIMEOUT or LOCK_TIMEOUT times have elapsed. Since these statements enable you to specify the number of seconds that IAF is to wait for a response before timing out, and iBrowsers heartbeat idle time is controlled every 2 minutes, a reasonable setting for these statements would be a value 10 seconds less than multiples of 2 minutes such as 110, 230, and so on. For example, if TIMEOUT is set to 30, the timeout will not actually occur for two minutes of idle time (when the heartbeat goes off). If it is set to 150, the

Language Statements IAF 8.0 DML

6-357

SET LOCK_TIMEOUT

timeout will not occur for 4 minutes of idle time, when the second heartbeat goes off. The reason for the 10 second less-than multiple of 2 minutes recommendation is because the heartbeats are not guaranteed to be exact. For example, if you specify the TIMEOUT as 120 and the first heartbeat actually goes off at 119.99, the timeout will not happen for 4 minutes of idle time when the second heartbeat occurs.

Example
SET LOCK_TIMEOUT 15

Related Topics
The following references contain information pertaining to the SET LOCK_TIMEOUT statement: This chapters discussions of the SET TIMEOUT and SHOW TIMEOUT statements. The discussion of blocks in this manuals Blocks and Block Qualifiers chapter. The discussion of transactions in the IAF Users Guide.

6-358

Language Statements IAF 8.0 DML

SET LOG_FILE

SET LOG_FILE
Syntax
SET LOG_FILE "filespec"

Category
System Settings

Description
This statement specifies the log file for the application. If this command is not used, the default log file is:
GEM_ROOT:log/dmltrace.log

Messages are appended to the log file with the LOG statement. If the log file is missing, it will be created if possible - no folders will be created if folders specified in the log file path are missing. The log file is UTF-8 encoded.

Example 1
SET LOG_FILE "c:\tmp\dmltrace.log"

Example 2
The log file can also be set using the GEM_LOG_FILE SCV. The format is as follows:
GEM_LOG_FILE=filespec

This can be specified in the usual SCV places, for example the Application's resource file:
set_env=GEM_LOG_FILE=c:\temp\dmldebug.log

When setting the GEM_LOG_FILE SCV in the application resource file, the special tokens %home and %username can be used as place holders for the user's home directory and username, respectively, and these tokens will be replaced by their current values for each user.

Examples:
set_env=GEM_LOG_FILE=C:\temp\%username.log set_env=GEM_LOG_FILE=%home\logs\dmltrace.log

Language Statements IAF 8.0 DML

6-359

SET LOG_FILE

Note that if the log file does not exist it will be created, but no missing directories in the file path will be created. Therefore, use of %username as in the following example will require that a folder is created for each user prior to use of the log command.
set_env=GEM_LOG_FILE=c:\logs\%username\dmltrace.log

Related Topics
The following references contain information pertaining to the SET LOG_FILE statement: This chapter's discussion of the SET LOG_LEVEL, LOG and SHOW LOG statements.

6-360

Language Statements IAF 8.0 DML

SET LOG_LEVEL

SET LOG_LEVEL
Syntax
SET LOG_LEVEL level

Category
System Settings

Description
This statement specifies the log level for the application. Valid levels are ERROR, WARNING, INFO and DEBUG. Logging cannot be turned off. If this command is not used, the default logging level is ERROR.

Example 1
SET LOG_LEVEL DEBUG

Example 2
The log level can also be set using the GEM_LOG_LEVEL SCV. The format is as follows:
GEM_LOG_LEVEL=level

This can be specified in the usual SCV places, for example the Application's resource file:
set_env=GEM_LOG_LEVEL=DEBUG

Related Topics
The following references contain information pertaining to the SET LOG_LEVEL statement: This chapter's discussion of the SET LOG_FILE, LOG and SHOW LOG statements.

Language Statements IAF 8.0 DML

6-361

SET MASK_CURRENCY_SIGN

SET MASK_CURRENCY_SIGN
Syntax
SET MASK_CURRENCY_SIGN currency-sign-character

Category
System settings

Description
This statement sets the currency sign mask character.

Related Topics
See also the SHOW MASK_CURRENCY_SIGN statement, the %MASK_CURRENCY_SIGN special variable, and depending on your platform, either the GEM_CURRENCY environment variable or the SYS$CURRENCY logical. The following statements, special variables, environment variables, and logicals are also related to mask character settings: SET/SHOW MASK_DIGIT_SEPARATOR, GEM_DIGIT_SEP, SYS$DIGIT_SEP, SET/SHOW MASK_RADIX_POINT, GEM_RADIX_POINT and SYS$RADIX_POINT.

6-362

Language Statements IAF 8.0 DML

SET MASK_DIGIT_SEPARATOR

SET MASK_DIGIT_SEPARATOR
Syntax
SET MASK_DIGIT_SEPARATOR digit-separator-character

Category
System settings

Description
This statement sets the digit separator mask character.

Related Topics
See also the SHOW MASK_DIGIT_SEPARATOR statement, the %MASK_DIGIT_SEPARATOR special variable, and depending on your platform, either the GEM_DIGIT_SEP environment variable or the SYS$DIGIT_SEP logical. The following statements, special variables, environment variables, and logicals are also related to mask character settings: SET/SHOW MASK_CURRENCY_SIGN, GEM_CURRENCY, SYS$CURRENCY, SET/SHOW MASK_RADIX_POINT, GEM_RADIX_POINT and SYS$RADIX_POINT.

Language Statements IAF 8.0 DML

6-363

SET MASK_RADIX_POINT

SET MASK_RADIX_POINT
Syntax
SET MASK_RADIX_POINT radix-point-character

Category
System settings

Description
This statement sets the radix point mask character.

Related Topics
See also the SHOW MASK_RADIX_POINT statement, the %MASK_RADIX_POINT special variable, and depending on your platform, either the GEM_RADIX_POINT environment variable or the SYS$RADIX_POINT logical. The following statements, special variables, environment variables, and logicals are also related to mask character settings: SET/SHOW MASK_CURRENCY_SIGN, GEM_CURRENCY, SYS$CURRENCY, SET/SHOW MASK_DIGIT_SEPARATOR, GEM_DIGIT_SEP and SYS$DIGIT_SEP.

6-364

Language Statements IAF 8.0 DML

SET NOVERIFY

SET NOVERIFY
Syntax
SET NOVERIFY

Category
System settings

Description
This statement causes IAF not to display individual DML statements from indirect command files when you execute such files at the IAF command line prompt (GEM> by default) via the @ command. If you execute a SET VERIFY statement, IAF displays individual DML statements from indirect command files during their execution. By default, IAF does not display individual DML statements from indirect command files during their execution.

Related Topics
The following references contains information pertaining to the SET NOVERIFY statement: This chapters discussion of the SET VERIFY statement. The discussion of the system developers interface in the IAF System Reference Manual.

Language Statements IAF 8.0 DML

6-365

SET OVERFLOW

SET OVERFLOW
Syntax
SET OVERFLOW=(FLOATING=f, INTEGER=i)

Category
System settings

Description
This statement causes IAF to control when and if arithmetic overflow occurs. Valid values for f are ON to turn floating overflow and underflow checking on, OFF to turn them off, and nnnnnn to turn them on at 0.1E+nnnnnn and 0.1E-nnnnnn, respectively. The keyword DOUBLE can also be used as a synonym for the value 309, which is close to the double precision floating oint exponent range. FLOATING=0 is the same as FLOATING=OFF. Valid values for i are ON to turn integer overflow checking on, OFF to turn it off, and nn to turn it on at nn decimal digits. The keyword LONGWORD can also be used to set overflow checking to the range 2^31 to 2^31-1. INTEGER=0 is the same as INTEGER=OFF. Turning integer overflow off causes integer arithmetic operations that would otherwise cause an integer overflow error to instead round to the result of 86 significant digits.

Example
OVERFLOW=(FLOATING=OFF, INTEGER=OFF)

Related Topics
The following references contain information pertaining to the SET OVERFLW statement: This chapters discussion of the SHOW OVERFLOW statement

6-366

Language Statements IAF 8.0 DML

SET PERFORM

SET PERFORM
Syntax
SET PERFORM option_keyword

Category
System settings

Description
This statement indicates the type of file IAF is to perform when executing a PERFORM, SWITCH, or SWITCH_BASE statement that does not include a filetype specification. The types of files to which these statements can apply are DML source files (filetype .dml) or DML compiled files (filetype .dmc).

Option Keywords
The following table lists and describes the option keywords that are valid for use with the SET PERFORM statement. Option Keyword DMC_DML Description This keyword causes IAF to search first for a compiled DML file having the specified filename. If IAF finds no such file, it searches for a DML source file having the specified filename. IAF displays an error message if it finds no source or compiled file having the specified filename. This keyword causes IAF to search for only a compiled DML file having the specified filename, and to display an error message if it finds no such file. This keyword causes IAF to search first for a DML source file having the specified filename. If IAF finds no such file, it searches for a compiled DML file having the specified filename. IAF displays an error message if it finds no source or compiled file having the specified filename.

DMC_ONLY

DML_DMC

Language Statements IAF 8.0 DML

6-367

SET PERFORM

Option Keyword DML_ONLY

Description This keyword causes IAF to search for only a DML source file having the specified filename, and to display an error message if it finds no such file.

Example
SET PERFORM DMC_DML

Related Topics
The following references contain information pertaining to the SET PERFORM statement: This chapters discussions of the SHOW PERFORM, PERFORM, SWITCH, and SWITCH_BASE statements.

6-368

Language Statements IAF 8.0 DML

SET PRECISION

SET PRECISION
Syntax
SET PRECISION floating_point_number

Category
System settings

Description
This statement specifies a floating point number indicating the minimum difference that must exist between two numbers for IAF to consider them unequal. IAF considers two numbers to be equal if their difference is less than the precision value. For example, given the following variable definitions:
#A=5.00000000#B=4.99999999

IAF considers #A and #B to be equal if the current precision is .0000001 (the default precision). The following operations have the given results based upon these variables and the default precision:
(#A=#B)true (#A<=#B)true (#A>=#B)true (#A<>#B)false (#A<#B)false (#A>#B)false

Given the following variable definitions and the default precision:

#C=5.0000#D=4.9999

IAF considers #C and #D to be unequal. The following operations have the given results based upon these variables and the default precision.
(#C=#D)false (#C<=#D)false (#C>=#D)true (#C<>#D)true (#C<#D)false (#C>#D)true

Language Statements IAF 8.0 DML

6-369

SET PRECISION

A precision of zero means that floating point numbers must match exactly to be equal. Note that when rounding floating point numbers (i.e. via the ROUND built-in DML function), the number of decimal places to which you are rounding must be less than the number of places specified for the precision level to produce a meaningful result. For details regarding the ROUND built-in function, refer to this manuals BUILT-IN FUNCTIONS chapter.
floating_point_number

This is a floating point number indicating the minimum difference that must exist between two numbers for IAF to consider them unequal.

Examples
SET PRECISION 0.00000000001 SET PRECISION 1E-6

Related Topics
The following references contain information pertaining to the SET PRECISION statement: This chapters discussion of the SHOW PRECISION statement. This discussion of operators in this manuals EXPRESSIONS chapter.

6-370

Language Statements IAF 8.0 DML

SET PROMPT

SET PROMPT
Syntax
SET PROMPT expression

Category
System settings

Description
This statement sets the developers interface prompt (i.e. the IAF command line prompt). By default, the IAF command line prompt is GEM>. You can specify any valid DML expression as the prompt. However, note that if you specify a prompt via this statement, subsequent interrupt sessions prompts do not display a suffix indicating the current interrupt level.
expression

This is an expression indicating the prompt to appear at the IAF command line.

Examples
SET PROMPT $ SET PROMPT (%TODAY & >)

Reference
The following reference contains information pertaining to the SET PROMPT statement: This chapters discussion of the SET INTERRUPT statement.

Language Statements IAF 8.0 DML

6-371

SET SCREEN

SET SCREEN
Syntax
SET SCREEN option_keyword[,option_keyword]

Category
System settings

Description
This statement enables you to specify screen characteristics that IAF is to use. Option Keywords The following table lists and describes the keywords that are valid for use with the SET SCREEN statement. Option Keyword BORDER Description This keyword indicates that all windows are to have borders, unless specified otherwise via an appropriate form qualifier. This is a default behavior. This keyword indicates that windows are not to have borders, regardless of any form specifications to the contrary. This helps to reduce screen output when using slow speed communication lines. This keyword indicates that screen updates are to occur when output is sent to the screen, and IAF is to display all intermediate outputs.

NOBORDER

NOUPDATE_ON_INPU T

6-372

Language Statements IAF 8.0 DML

SET SCREEN

Option Keyword UPDATE_ON_INPUT

Description This keyword enables batched display updating. In this screen mode, IAF attempts to optimize display updates and remove unnecessary display updates whenever possible. This is a default behavior. The following operations cause IAF to enable output batching: >Completing a NORMAL, TABLE_EDIT, or MENU form. >Exiting a MENU BLOCK. >Exiting a line in a TABLE_EDIT form. >Executing a DISPLAY BEGIN_UPDATE statement. IAF disables batch screen updating and restores the screen to the current status when: >An input request takes place (except for MENU_BLOCK inputs, or when the user has typed ahead.) >Execution of a DISPLAY FLUSH statement takes place.

Examples
SET SCREEN BORDER SET SCREEN NOBORDER, UPDATE_ON_INPUT

Related Topics
The following references contain information pertaining to the SET SCREEN statement: This chapters discussion of the DISPLAY statement. The discussion of blocks in this manuals Blocks and Block Qualifiers chapter. The discussion of forms in this manuals Forms and Form Qualifiers chapter.

Language Statements IAF 8.0 DML

6-373

SET SHADOWS

SET SHADOWS
Syntax
SET SHADOWS number

Category
System settings

Description
This statement specifies the number of forms that are to remain on-screen before IAF is to begin removing old images. You can specify up to a maximum of 99 (the default) shadow forms. Recall that when a form that includes a /REMAIN qualifier executes, its screen image remains on screen after the form logically exits. This image is a shadow form. The SET SHADOWS statement enables you to prevent the screen from becoming cluttered. Note that a SET SHADOWS statement specifying a value of 0 effectively disables the /REMAIN qualifier.
number

This is the number of shadow forms that are to remain on-screen before IAF is to begin removing old images.

Example
SET SHADOWS 8

Related Topics
The following references contain information pertaining to the SET SHADOWS statement: This chapters discussion of the SHOW SHADOWS statement. The discussion of the /REMAIN qualifier in this manuals Forms and Form Qualifiers chapter.

6-374

Language Statements IAF 8.0 DML

SET STATUS_FREQUENCY

SET STATUS_FREQUENCY
Syntax
SET STATUS_FREQUENCY seconds

Category
System settings

Description
This statement adjusts the rate in seconds at which status displays are updated.

Examples
SET STATUS_FREQUENCY 5

Related Topics
See also the SHOW STATUS_FREQUENCY command and the %STATUS_FREQUENCY special variable as well as the /STATUS and /NOSTATUS qualifiers that can be specified on certain form statements.

Language Statements IAF 8.0 DML

6-375

SET SYSTEM

SET SYSTEM
Syntax
SET SYSTEM [database_handle.]system_name

Category
System settings

Description
This statement sets the current default system. IAF uses the default system that this statement specifies when executing statements or forms that reference a facility without explicitly specifying a system.
database_handle

This is the handle for the database in which the specified system exists. It is necessary to include a database handle only if you have invoked multiple databases, and the given system does not exist in the current default database.
system_name

This is the name of the system that is to be the current default system.

Examples
SET SYSTEM ACCOUNTS_PAYABLE SET SYSTEM ACCTS.BILLING

Related Topics
The following references contain information pertaining to the SET SYSTEM statement: This chapters discussion of the SHOW SYSTEM statement. The discussion of the System Definition Editor in the IAF System Reference Manual.

6-376

Language Statements IAF 8.0 DML

SET TIMEOUT

SET TIMEOUT
Syntax
SET TIMEOUT seconds

Category
System settings

Description
This statement enables you to specify the number of seconds that IAF is to wait for a response at an input block of any kind before timing out. If the given number of seconds pass, IAF automatically exits the form, and rolls back or commits the current transaction as it would if the end user had pressed the GM_EXIT key at the input. If both a SET TIMEOUT value and a SET LOCK_TIMEOUT value are specified, IAF uses the LOCK_TIMEOUT value while a read-write transaction exists and the TIMEOUT value otherwise.
seconds

This is the number of seconds that IAF is to wait for a response at an input block of any kind before timing out. Specifying zero seconds disables the timeout function.

iBrowser-specific Behavior
Starting with V7.0.0B SP1, SET TIME_OUT and SET LOCK_TIMEOUT have been implemented utilizing iBrowsers heartbeat. The heartbeat occurs in multiples of 2 minutes at which time it will check to see if the TIMEOUT or LOCK_TIMEOUT times have elapsed. Since these statements enable you to specify the number of seconds that IAF is to wait for a response before timing out, and iBrowsers heartbeat idle time is controlled every 2 minutes, a reasonable setting for these statements would be a value 10 seconds less than multiples of 2 minutes such as 110, 230, and so on. For example, if TIMEOUT is set to 30, the timeout will not actually occur for two minutes of idle time (when the heartbeat goes off). If it is set to 150, the timeout will not occur for 4 minutes of idle time, when the second heartbeat goes off.

Language Statements IAF 8.0 DML

6-377

SET TIMEOUT

The reason for the 10 second less-than multiple of 2 minutes recommendation is because the heartbeats are not guaranteed to be exact. For example, if you specify the TIMEOUT as 120 and the first heartbeat actually goes off at 119.99, the timeout will not happen for 4 minutes of idle time when the second heartbeat occurs.

Examples
SET TIMEOUT 20 SET TIMEOUT 0

Related Topics
The following references contain information pertaining to the SET TIMEOUT statement: This chapters discussions of the SET LOCK_TIMEOUT and SHOW TIMEOUT statements. The discussion of blocks in this manuals BLOCKS AND BLOCK QUALIFIERS chapter. The discussion of transactions in the IAF Users Guide.

6-378

Language Statements IAF 8.0 DML

SET TITLE_BAR

SET TITLE_BAR
Syntax
SET TITLE_BAR string_expression

Category
System settings

Description
This statement enables you to specify the text that is to appear in the title bar of the IAF application window when running IAF in an environment that supports a graphical user interface.
string_expression

This is a string expression indicating the text that is to appear in the title bar of the IAF application window.

Examples
SET TITLE_BAR IAF Client

Related Topics
The following references contain information pertaining to the SET TITLE_BAR statement: The Guide to Using IAF Client for Windows and the Guide to Using IAF Client for Windows Profressional.

Language Statements IAF 8.0 DML

6-379

SET TITLE_FORM

SET TITLE_FORM
Syntax
SET TITLE_FORM filename

Category
System settings

Description
This statement enables you to specify the name of the DML file that IAF is to perform each time execution of a TITLE statement or invocation of a IAF utility takes place. The specified DML file must exist when execution of the SET TITLE_FORM takes place. If you modify the current title form, you must subsequently execute the SET TITLE_FORM statement for IAF to use the modified title form.
filename

This is a specification uniquely identifying the DML file that holds the form that is to be the title form.

Examples
SET TITLE_FORM ACC_PAY:TITLE_FORM SET TITLE_FORM SYS:SCREEN_HEADINGS

Related Topics
The following references contain information pertaining to the SET TITLE_FORM statement: This chapters discussion of the SHOW TITLE_FORM statement. The discussion of the TITLE declaration statement in this manuals Title Declarations chapter. The discussion of screen facilities in the IAF System Reference Manual.

6-380

Language Statements IAF 8.0 DML

SET VERIFY

SET VERIFY
Syntax
SET VERIFY

Category
System settings

Description
This statement causes IAF to display individual DML statements from indirect command files when you execute such files at the IAF command line prompt (GEM> by default) via the @ command. If you execute a SET NOVERIFY statement, IAF disables the display of individual DML statements from indirect command files during their execution. By default, IAF does not display individual DML statements from indirect command files during their execution.

Related Topics
The following references contains information pertaining to the SET VERIFY statement: This chapters discussion of the SET NOVERIFY statement. The discussion of the system developers interface in the IAF System Reference Manual.

Language Statements IAF 8.0 DML

6-381

SET WD

SET WD
Syntax
SET WD directory

Category
Miscellaneous

Description
This statement sets the users current working directory (aka default directory). See also the CD and SET DEFAULT statements.

6-382

Language Statements IAF 8.0 DML

SHOW CAT_FILTER

SHOW CAT_FILTER
Syntax
SHOW CAT_FILTER

Category
System settings

Description
This statement shows the table associated with the GEM_CAT_RELATION_FIELDS_FILTER virtual table and the special variable %CAT_FILTER

Related Topics
See also the SET CAT_FILTER statement and the %CAT_FILTER special variable.

Language Statements IAF 8.0 DML

6-383

SHOW DATABASE

SHOW DATABASE
Syntax
SHOW DATABASE

Category
System settings

Description
This statement displays the name of the current default database.

Related Topics
The following references contain information pertaining to the SHOW DATABASE statement: This chapters discussions of the SET DATABASE and INVOKE statements. The discussion of the GEM_DATABASE_n SCV in the IAF guide that applies to your operating system.

6-384

Language Statements IAF 8.0 DML

SHOW DATE_FORMAT

SHOW DATE_FORMAT
Syntax
SHOW DATE_FORMAT

Category
System settings

Description
This statement displays the current date input format.

Related Topics
The following references contain information pertaining to the SHOW DATE_FORMAT statement: This chapters discussion of the SET DATE_FORMAT statement. The discussion of dates in the IAF Users Guide.

Language Statements IAF 8.0 DML

6-385

SHOW DEFAULT

SHOW DEFAULT
Syntax
SHOW DEFAULT

Category
Miscellaneous

Description
Shows the users default directory (aka current working directory). See also the PWD and SHOW WD statements and the %WD special variable.

6-386

Language Statements IAF 8.0 DML

SHOW ENTRY_MENU

SHOW ENTRY_MENU
Syntax
SHOW ENTRY_MENU

Category
System settings

Description
This statement displays the name of the menu that is to automatically execute upon entering IAF.

Related Topics
The following references contain information pertaining to the SHOW ENTRY_MENU statement: This chapters discussion of the SET ENTRY_MENU statement. The discussion of the System Definition Editor in the IAF System Reference Manual.

Language Statements IAF 8.0 DML

6-387

SHOW EXIT FORM

SHOW EXIT FORM

Syntax
SHOW EXIT FORM

Category
System settings

Description
This statement displays a message indicating the state of the global exit handler form. If the global exit handler is disabled, a message similar to the following is displayed: Exit form: OFF If the global exit handler is enabled, a message similar to the following is displayed: Exit form: ON If the global exit handler is enabled and is executing, a message similar to the following is displayed: Exit form: ON, EXECUTING (However, if an exit handler form is actually executing, the user interface will likely be in simplified or silent mode and no output will be seen!)

Related Topics
See also the SET /GLOBAL EXIT FORM, SET /LOCAL EXIT FORM, SET /GLOBAL EXIT OFF and SET /LOCAL EXIT OFF statements as well as the %EXIT_FORM_ENABLED, %EXIT_FORM_ACTIVE, %EXIT_FORM_FILENAME and %EXIT_FORM_FORMNAME special variables.

6-388

Language Statements IAF 8.0 DML

SHOW FIELDS FOR

SHOW FIELDS FOR

Syntax
SHOW FIELDS FOR table_specification

Category
Utilities and program development

Description
This statement causes IAF to display the names of the fields that reside in the given table(s).
table_specification

This is a specification indicating the table(s) for which the SHOW FIELDS FOR statement is to display field names. The table specification can include the wildcard characters * and %, where * represents zero or more unknown characters, and % represents a single unknown character.

Examples
SHOW FIELDS FOR CUSTOMERS

This example causes IAF to display a list of all fields that reside in the CUSTOMERS table.
SHOW FIELDS FOR M*

This example causes IAF to display a list of all fields that reside in tables having names beginning with M.
SHOW FIELDS FOR REGION%

This example causes IAF to display a list of all fields that reside in tables having names beginning with REGION optionally followed by one other character (e.g. REGION, REGIONS, REGION2).

Related Topics
The following reference contains information pertaining to the SHOW FIELDS FOR statement:

Language Statements IAF 8.0 DML

6-389

SHOW FIELDS FOR

The discussion of fields and tables in the IAF guide that applies to your database engine.

6-390

Language Statements IAF 8.0 DML

SHOW HELP

SHOW HELP
Syntax
SHOW HELP

Category
System settings

Description
This statement displays a message indicating whether single line help text at the bottom of the screen is currently enabled or disabled.

Related Topics
The following references contain information pertaining to the SHOW HELP statement: This chapters discussions of the SET HELP ON and SET HELP OFF statements.

Language Statements IAF 8.0 DML

6-391

SHOW HOSTID

SHOW HOSTID
Syntax
SHOW HOSTID

Category
Miscellaneous

Description
Shows a space separated list of HOSTIDs for the machine on which IAF is running. See also the %HOSTID special variable. These are used by IAF licensing.

6-392

Language Statements IAF 8.0 DML

SHOW ICON NAME

SHOW ICON NAME

Syntax
SHOW ICON_NAME

Category
System settings

Description
This statement shows the text that appears below the Thin Client and GCWPRO icons.

Related Topics
See also the SET ICON_NAME, SET TITLE_BAR and SHOW TITLE_BAR statements.

Language Statements IAF 8.0 DML

6-393

SHOW INPUT

SHOW INPUT
Syntax
SHOW INPUT

Category
System settings

Description
This statement shows the foreground and background display attributes to use for screen output areas (these include input areas after input is done).

Related Topics
See also the SET INPUT_BACKGROUND and SET INPUT_FOREGROUND statements as well as the %INPUT_BACKGROUND and %INPUT_FOREGROUND special variables.

6-394

Language Statements IAF 8.0 DML

SHOW INTERRUPT

SHOW INTERRUPT
Syntax
SHOW INTERRUPT

Category
System settings

Description
This statement displays the statement that IAF is to execute whenever an end user presses the GM_INTERRUPT key.

Related Topics
The following references contain information pertaining to the SHOW INTERRUPT statement: This chapters discussion of the SET INTERRUPT statement. The discussion of key facilities in the IAF Conventions Guide.

Language Statements IAF 8.0 DML

6-395

SHOW KEYBOARD

SHOW KEYBOARD
Syntax
SHOW KEYBOARD

Category
System settings

Description
This statement displays the name of the keyboard definition file that is currently in use.

Related Topics
The following references contain information pertaining to the SHOW KEYBOARD statement: This chapters discussion of the SET KEYBOARD statement. The IAF Conventions Guide.

6-396

Language Statements IAF 8.0 DML

SHOW LOCK

SHOW LOCK
Syntax
SHOW LOCK

Category
System settings

Description
This statement displays the currently enabled lock mode(s).

Related Topic
The following references contain information pertaining to the SHOW LOCK statement: This chapters discussion of the SET LOCK statement. The discussion of locking strategies in the IAF guide that applies to your database engine.

Language Statements IAF 8.0 DML

6-397

SHOW LOCK_TIMEOUT

SHOW LOCK_TIMEOUT
Syntax
SHOW LOCK_TIMEOUT

Category
System settings

Description
This statement displays the number of seconds that IAF is to wait for a response at an input block of any kind before timing out, and is applicable only when an end user has a current read-write transaction on the database.

Related Topics
See also the SET LOCK_TIMEOUT, SET TIMEOUT and SHOW TIMEOUT statements.

6-398

Language Statements IAF 8.0 DML

SHOW LOG

SHOW LOG
Syntax
SHOW LOG

Category
System Settings

Description
This statement displays the log file specification, and the logging level.

Example
DML> show log LOG_LEVEL: ERROR, LOG_FILE: "c:\tmp\dmltrace.log"

Related Topics
The following references contain information pertaining to the SET LOG_LEVEL statement: This chapter's discussion of the SET LOG_FILE, SET LOG_LEVEL and LOG statements.

Language Statements IAF 8.0 DML

6-399

SHOW MASK_CURRENCY_SIGN

SHOW MASK_CURRENCY_SIGN
Syntax
SHOW MASK_CURRENCY_SIGN

Category
System settings

Description
This statement shows the currently set currency sign mask character.

Related Topics
See also the SET MASK_CURRENCY_SIGN statement, the %MASK_CURRENCY_SIGN special variable, and depending on your platform, either the GEM_CURRENCY environment variable or the SYS$CURRENCY logical. The following statements, special variables, environment variables, and logicals are also related to mask character settings: SET/SHOW MASK_DIGIT_SEPARATOR, GEM_DIGIT_SEP, SYS$DIGIT_SEP, SET/SHOW MASK_RADIX_POINT, GEM_RADIX_POINT and SYS$RADIX_POINT.

6-400

Language Statements IAF 8.0 DML

SHOW MASK_DIGIT_SEPARATOR

SHOW MASK_DIGIT_SEPARATOR
Syntax
SHOW MASK_DIGIT_SEPARATOR

Category
System settings

Description
This statement shows the currently set digit separator mask character.

Related Topics
See also the SET MASK_DIGIT_SEPARATOR statement, the %MASK_DIGIT_SEPARATOR special variable, and depending on your platform, either the GEM_DIGIT_SEP environment variable or the SYS$DIGIT_SEP logical. The following statements, special variables, environment variables, and logicals are also related to mask character settings: SET/SHOW MASK_CURRENCY_SIGN, GEM_CURRENCY, SYS$CURRENCY, SET/SHOW MASK_RADIX_POINT, GEM_RADIX_POINT and SYS$RADIX_POINT.

Language Statements IAF 8.0 DML

6-401

SHOW MASK_RADIX_POINT

SHOW MASK_RADIX_POINT
Syntax
SHOW MASK_RADIX_POINT

Category
System settings

Description
This statement shows the currently set radix point mask character.

Related Topics
See also the SET MASK_RADIX_POINT statement, the %MASK_RADIX_POINT special variable, and depending on your platform, either the GEM_RADIX_POINT environment variable or the SYS$RADIX_POINT logical. The following statements, special variables, environment variables, and logicals are also related to mask character settings: SET/SHOW MASK_CURRENCY_SIGN, GEM_CURRENCY, SYS$CURRENCY, SET/SHOW MASK_DIGIT_SEPARATOR, GEM_DIGIT_SEP and SYS$DIGIT_SEP.

6-402

Language Statements IAF 8.0 DML

SHOW OVERFLOW

SHOW OVERFLOW
Syntax
SHOW OVERFLOW

Category
System settings

Description
This statement displays the current integer overflow setting.

Related Topic
The following references contain information pertaining to the SHOW LOCK statement: This chapters discussion of the SET OVERFLOW statement.

Language Statements IAF 8.0 DML

6-403

SHOW PERFORM

SHOW PERFORM
Syntax
SHOW PERFORM

Category
System settings

Description
This statement displays the type of file IAF is to perform when executing a PERFORM, SWITCH, or SWITCH_BASE statement that does not specify a filetype.

Related Topics
The following references contain information pertaining to the SHOW PERFORM statement: This chapters discussions of the SET PERFORM, PERFORM, SWITCH, and SWITCH_BASE statements.

6-404

Language Statements IAF 8.0 DML

SHOW PLATFORM

SHOW PLATFORM
Syntax
SHOW PLATFORM

Category
Miscellaneous

Description
Shows the operating system platform that is used by IAF licensing. See also the %PLATFORM special variable.

Language Statements IAF 8.0 DML

6-405

SHOW PRECISION

SHOW PRECISION
Syntax
SHOW PRECISION

Category
System settings

Description
This statement shows the numeric precision that IAF is currently using.

Related Topics
The following reference contains information pertaining to the SHOW PRECISION statement: This chapters discussion of the SET PRECISION statement.

6-406

Language Statements IAF 8.0 DML

SHOW PROMPT

SHOW PROMPT
Syntax
SHOW PROMPT

Category
System settings

Description
This statement shows the currently set DML developers command line interface prompt. By default, the DML developers command line prompt is DML> .

Related Topics
See also the SET PROMPT statement and the %INPUT_PROMPT special variable.

Language Statements IAF 8.0 DML

6-407

SHOW SHADOWS

SHOW SHADOWS
Syntax
SHOW SHADOWS

Category
System settings

Description
This statement shows the number of forms that must be on screen before IAF is to begin removing old images.

Related Topics
The following reference contains information pertaining to the SHOW SHADOWS statement: This chapters discussion of the SET SHADOWS statement.

6-408

Language Statements IAF 8.0 DML

SHOW STATUS_FREQUENCY

SHOW STATUS_FREQUENCY
Syntax
SHOW STATUS_FREQUENCY

Category
System settings

Description
This statement displays the frequency at which status displays are updated.

Related Topics
See also the SET STATUS_FREQUENCY statement and the %STATUS_FREQUENCY special variable as well as the /STATUS and /NOSTATUS qualifiers that can be specified on certain form statements.

Language Statements IAF 8.0 DML

6-409

SHOW SYSTEM

SHOW SYSTEM
Syntax
SHOW SYSTEM

Category
System settings

Description
This statement displays the name of the current default system.

Related Topics
The following references contain information pertaining to the SHOW SYSTEM statement: This chapters discussion of the SET SYSTEM statement. The discussion of the System Definition Editor in the IAF System Reference Manual.

6-410

Language Statements IAF 8.0 DML

SHOW TABLES FOR

SHOW TABLES FOR

Syntax
SHOW TABLES FOR field_specification

Category
Utilities and program development

Description
This statement causes IAF to display the names of the tables that hold the given field(s).
field_specification

This is a specification indicating the field(s) for which the SHOW TABLES FOR statement is to display table names. The field specification can include the wildcard characters * and %, where * represents zero or more unknown characters, and % represents a single unknown character.

Examples
SHOW TABLES FOR CUSTOMER_NUMBER

This example causes IAF to display a list of all tables that hold the CUSTOMER_NUMBER field.
SHOW TABLES FOR M*

This example causes IAF to display a list of all tables that hold fields having names beginning with M.
SHOW TABLES FOR TEST%

This example causes IAF to display a list of all tables that hold fields having names beginning with TEST optionally followed by one other character (e.g. TEST, TESTS, TEST5).

Related Topics
The following reference contains information pertaining to the SHOW TABLES FOR statement:

Language Statements IAF 8.0 DML

6-411

SHOW TABLES FOR

The discussion of fields and tables in the IAF guide that applies to your database engine.

6-412

Language Statements IAF 8.0 DML

SHOW TARGETID

SHOW TARGETID
Syntax
SHOW TARGETID

Category
Miscellaneous

Description
Shows the TARGETID for the machine on which IAF is running. See also the %TARGETID special variable. This is used by IAF licensing. This is an obsolete statement.

Language Statements IAF 8.0 DML

6-413

SHOW TIMEOUT

SHOW TIMEOUT
Syntax
SHOW TIMEOUT

Category
System settings

Description
This statement displays the number of seconds IAF is to wait for a response at an input block of any kind before timing out.

Related Topics
The following references contain information pertaining to the SHOW TIMEOUT statement: This chapters discussions of the SET TIMEOUT and SET LOCK_TIMEOUT statements.

6-414

Language Statements IAF 8.0 DML

SHOW TITLE_BAR

SHOW TITLE_BAR
Syntax
SHOW TITLE_BAR

Category
System settings

Description
This statement shows the text that appears in the Thin Client and GCWPRO title bars.

Related Topics
See also the SET TITLE_BAR, SET ICON_NAME and SHOW ICON_NAME statements.

Language Statements IAF 8.0 DML

6-415

SHOW TITLE_FORM

SHOW TITLE_FORM
Syntax
SHOW TITLE_FORM

Category
System settings

Description
This statement displays the name of the DML file that IAF is to perform when execution of a TITLE statement or invocation of a IAF utility takes place.

Related Topics
The following references contain information pertaining to the SHOW TITLE_FORM statement: This chapters discussion of the SET TITLE_FORM statement. The discussion of the TITLE declaration statement in this manuals Title Declarations chapter. The discussion of screen facilities in the IAF System Reference Manual.

6-416

Language Statements IAF 8.0 DML

SHOW VERIFY

SHOW VERIFY
Syntax
SHOW VERIFY

Category
System settings

Description
This statement displays the ON/OFF indirect command file execution verification setting as set with the SET VERIFY or SET NOVERIFY statements.

Related Topics
See also the SET VERIFY and SET NOVERIFY statements.

Language Statements IAF 8.0 DML

6-417

SHOW WD

SHOW WD
Syntax
SHOW WD

Category
Miscellaneous

Description
Shows the users current working directory (default directory). See also the PWD and SHOW DEFAULT statements and the %WD special variable.

6-418

Language Statements IAF 8.0 DML

SIGNATURE

SIGNATURE
General Purpose
The SIGNATURE statement provides the application developer with the means to perform a non-interactive electronic signature. When username2 is specified, then this indicates a double electronic signature. The optional validation form is called then the username(s) and password(s) are authenticated by the operating system. Please refer to Appendix F, Electronic Signature and Audit Record for additional information.

Statement Syntax
Following is the syntax for the SIGNATURE statement:
SIGNATURE [/AUDIT=audit-file-specification] [/DATETIME=date-time] [/FACILITY=[[database-handle.][system-name:]]facility-name] [/FAILURE=(failure-dml)] [/NOAUDIT] /PASSWORD1=password-1 [/PASSWORD2=password-2] [/PURPOSE=purpose] [/SUCCESS=(success-dml)] /USERNAME1=username-1 [/USERNAME2=username-2] [/USER1=user-defined-1] [/USER2=user-defined-2] [/USER3=user-defined-3] [/USER4=user-defined-4] [/USER5=user-defined-5] [/VALIDATION_FORM=form-name] [/additional-qualifiers]

Language Statements IAF 8.0 DML

6-419

SIGNATURE

Implicit Block Actions

The username(s) and password(s) specified in the SIGNATURE statement are authenticated by the operating system regardless of whether or not an explicit VALIDATION_FORM is specified.

Special Considerations
In order to use a SIGNATURE statement on the UNIX platform, the IAF monitor must be running. On the UNIX platform, the system-level authentication of usernames and passwords is carried out by the IAF monitor on behalf of the user executing the SIGNATURE statement. If the IAF monitor is not running or is not responding, a message to that effect will be displayed and the SIGNATURE statement will fail. Any validation form specified is called before the username(s) and password(s) are authenticated by the operating system. If /USERNAME2=username-2 is specified, this indicates a double electronic signature. The same username may not be specified for both the /USERNAME1 and /USERNAME2 qualifiers. An audit record is appended to the audit file (unless /NOAUDIT is specified) regardless of the success or failure of the validation of the signature(s).

Specific Qualifiers
The following qualifiers have a specific definition in relation to a SIGNATURE statement:

/AUDIT
Syntax
/AUDIT=audit-file-specification

Description
This optional qualifier specifies the file to which the audit record is written. Audit-file-specification can be a quoted literal, a variable, a function, a table field or an expression in parentheses. An audit record is always written unless the /NOAUDIT qualifier is specified. You may not use both the /AUDIT and /NOAUDIT qualifier on the same SIGNATURE statement. Please see the section about the audit log file for more information on its format, contents and naming.

6-420

Language Statements IAF 8.0 DML

SIGNATURE

Example
/AUDIT="signature-audit-file

/DATETIME
Syntax
/DATETIME=date-time

Description
This optional qualifier specifies the location in which to store the date and time at which the electronic signature validation took place. The datetime occurs after the optional validation form returns, after the usernames and passwords are authenticated by the operating system, and just prior to any audit record being written. The date-time can be any variable or table field that is acceptable as the target of an input block.

Example
/DATETIME=#sig-date-time

/ERASE
The /ERASE qualifier is used to erase saved authentication information. The saved authentication information is erased as the last operation performed by the SIGNATURE_BLOCK or SIGNATURE statement. Thus if both /RECALL and /ERASE are specified, the authentication information is recalled, used, then erased.

/FACILITY
Syntax
/FACILITY /FACILITY=[[database-handle.][system-name:]]facility-name

Description
When the /FACILITY qualifier is present on a SIGNATURE statement, IAF checks to ensure that the specified username or usernames have access to the specified facility. Both /FACILITY (with no facility-name) and /FACILITY=facility-name are accepted. In the former case, the specified facility is the currently executing facility. In other words, when no facility-name is specified, the effect is the same as if /FACILITY=%FACILITY is specified.

Language Statements IAF 8.0 DML

6-421

SIGNATURE

/FAILURE
Syntax
/FAILURE=(dml-statement)

Description
This optional qualifier specifies a DML statement that IAF is to execute after the SIGNATURE statement completes when the specified usernames(s) and password(s) are determined to be invalid, either by the operating system or the optional validation routine. The special variable %STATUS is reset to %SUCCESS before the DML statement is executed. For a list of DML statements that the /FAILURE qualifier can execute, please refer to the appendix on EXECUTING DML STATEMENTS VIA QUALIFIERS in the IAF Data Manipulation Language manual.

Example
/FAILURE=(GOTO INVALID_SIGNATURE)

/NOAUDIT
Syntax /NOAUDIT

Description
This optional qualifier specifies that no audit record is to be written. An audit record is always written unless the /NOAUDIT qualifier is specified. You may not use both the /AUDIT and the /NOAUDIT qualifiers on the same SIGNATURE statement.

Example
/NOAUDIT

6-422

Language Statements IAF 8.0 DML

SIGNATURE

/PASSWORD1
Syntax
/PASSWORD1=password-1

Description
This qualifier specifies the password associated with the username that is specified with the /USERNAME1 qualifier. Password-1 can be a quoted string literal, variable, function, table field, special variable, or expression enclosed within parentheses. It cannot be overwritten by any action in the optional validation form. Note that when you use the /PASSWORD1 qualifier, you must also use the /USERNAME1 qualifier.

Example
/PASSWORD1=#todays_password

/PASSWORD2
Syntax
/PASSWORD2=password-2

Description
This optional qualifier specifies the password associated with the username that is specified with the /USERNAME2 qualifier. Password-2 can be a quoted string literal, variable, function, table field, special variable, or expression enclosed within parentheses. It cannot be overwritten by any action in the optional validation form. Note that when you use the /PASSWORD2 qualifier, you must also use the /USERNAME2 qualifier.

Example
/PASSWORD2=(#part1 & - & #part2)

Language Statements IAF 8.0 DML

6-423

SIGNATURE

/PURPOSE
Syntax
/PURPOSE=purpose

Description
This optional qualifier specifies the purpose of this SIGNATURE. The value is recorded in the audit record, if any, that is written for this action. On a SIGNATURE statement, purpose is always a source only. Purpose can be a quoted string literal, variable, function, table field, special variable, or expression enclosed within parentheses.

Example
/PURPOSE=#sig_purpose /PURPOSE=(#ro_purpose)

/RECALL
The /RECALL qualifier is used to recall the validated authentication information as saved by a prior SIGNATURE_BLOCK or SIGNATURE statement that used a /SAVE qualifier. If saved authentication information is present, then the SIGNATURE_BLOCK uses the saved information and does not prompt for any. The SIGNATURE statement similarly will use the saved authentication information in lieu of the authentication information specified on the SIGNATURE statement itself. Note that the purpose and /USER1 through /USER5 qualifier values are only overridden with saved information if they are not specified or are specified as null or blank on the SIGNATURE statement itself. Note that the SIGNATURE_BLOCK or SIGNATURE statement which uses the /SAVE qualifier must be compatible with the SIGNATURE_BLOCK or SIGNATURE statement which uses the /RECALL qualifier. Specifically, both blocks/statements must be either single or double signatures. It is not permissible for the first block/statement to be a single electronic signature and the second to be a double electronic signature (and vice versa). If this occurs in a SIGNATURE_BLOCK, the /RECALL qualifier will be ignored. If this occurs in a SIGNATURE statement, an error will be returned.

6-424

Language Statements IAF 8.0 DML

SIGNATURE

/SAVE
The /SAVE qualifier is used to save the validated authentication information entered by the user in a SIGNATURE_BLOCK or as specified by the program on a SIGNATURE statement for use by a future SIGNATURE_BLOCK or SIGNATURE statement. Only validated authentication information is saved. The purpose, usernames(s), password(s), and /USER1 through /USER5 qualifier values are saved. The DML compiler issues a compile-time error message when both /SAVE and /RECALL are used at the same time and when /SAVE and /ERASE are used at the same time.

/SUCCESS
Syntax
/SUCCESS=(success-dml)

Description This optional qualifier specifies a DML statement that IAF executes after the SIGNATURE statement completes when the usernames(s) and password(s) entered are accepted as valid, both by the operating system and any optional validation routine. For a list of DML statements that the /SUCCESS qualifier can execute, please refer to the appendix on Executing DML Statements via Qualifiers in the IAF Data Manipulation Language manual.

Example
/SUCCESS=(CONTINUE COMMIT)

/USERNAME1
Syntax
/USERNAME1=username-1

Description
This qualifier specifies the first username to be validated. Username-1 can be a quoted string literal, a variable, function, table field, special variable, or an expression enclosed within parentheses. When this qualifier is specified, it must be accompanied by a /PASSWORD1 qualifier.

Language Statements IAF 8.0 DML

6-425

SIGNATURE

Example
/USERNAME1=#this_user

/USERNAME2
Syntax
/USERNAME2=username-2

Description
This optional qualifier specifies that a double electronic signature is required. Username-2 can be a quoted string literal, a variable, function, table field, special variable, or an expression enclosed within parentheses. If this qualifier is specified, it must be accompanied by a /PASSWORD2 qualifier. Username-1 and username_2 must not be the same username.

Example
/USERNAME2=(#first_name & #last_name)

/USER1-5
Syntax
/USER1=user-defined-1 /USER2=user-defined-2 /USER3=user-defined-3 /USER4=user-defined-4 /USER5=user-defined-5

Description
These optional qualifiers specify values that are passed to the validation form and are also recorded in the signature audit file, if any. Their use and purpose is under the control of the validation form. User-defined-1 through user-defined-5 may be quoted string literals, variables, functions, table fields, special variables, or expressions enclosed in parentheses.

Example
/USER1=MANAGER

6-426

Language Statements IAF 8.0 DML

SIGNATURE

/VALIDATION_FORM
Syntax
/VALIDATION_FORM=form-name

Description
This optional qualifier specifies the name of a validation form that IAF executes before the username(s) and password(s) are authenticated by the operating system. (A PROCEDURE_FORM is recommended for this purpose.) The validation form must be located within the same form file as the SIGNATURE statement. See below for more information on the use of validation forms.

Example
/VALIDATION_FORM=cross_check_users

Exit Status
After the SIGNATURE statement executes, the special variable %STATUS is set to one of the following values: %SUCCESS if the username(s) were accepted by the optional validation form and successfully authenticated by the operating system. %FAILURE if the usernames(s) were rejected either by the optional validation routine or the operating system. Note: If a /FAILURE qualifier is defined and executes as a result of the invalid signature(s), then %STATUS is reset to %SUCCESS before the specified DML statement executes. %EXIT if the validation form returned a %EXIT status. If a /EXIT qualifier is defined and executes, then %STATUS is set to %SUCCESS before the associated DML is executed. %BACK if the validation form returned a %BACK status.

Language Statements IAF 8.0 DML

6-427

SLEEP

SLEEP
Syntax
SLEEP expression

Description
Expression is number of seconds, and can be: A constant A variable An (expression in parenthesis) And so on. The SLEEP command informs the server process to suspend execution for the allotted time, given in the EXPRESSION.

6-428

Language Statements IAF 8.0 DML

START_GTID

START_GTID
Syntax
START_GTID

Category
Data access

Description
This statement increments the %GTID_LEVEL (Global Transaction Identifier Level) special variable. The START_GTID and END_GTID statements are used to group a set of related database transactions into one single logical transaction. All database transactions in the logical transaction are given the same transaction identifier. The START_GTID and END_GTID statements are permitted to be nested. The START_GTID statement starts a logical transaction and increments %GTID_LEVEL. When the %GTID_LEVEL special variable transitions from 0 to 1, a transaction identifier is generated. The END_GTID statement decrements the %GTID_LEVEL special variable. The %GTID special variable never goes below zero. When the %GTID_LEVEL special variable is 0 (no logical transaction in progress), the transaction identifiers normally generated for each database transaction are used as usual. While the %GTID_LEVEL is non-zero, transaction identifiers are taken from the transaction identifier that was generated when %GTID_LEVEL transitioned from 0 to 1, not from the transaction identifier that was generated when %TRANS_LEVEL transitioned from 0 to 1.

Related Topicsf
See also the END_GTID statement and the %GTID and %GTID_LEVEL special variables as well as the "IAF Transaction Identifiers" appendix of this manual. Transaction identifiers are logged to every table involved in a transaction that contains a table-field named GEM_TRANSACTION_ID Transaction identifiers are also loosely related to the "Electronic

Language Statements IAF 8.0 DML

6-429

START_GTID

Signature and Audit Record" feature. Transaction identifiers are logged to the GEM_SIGNATURE_AUDIT table and to the electronic signature audit log file. See the "Electronic Signature and Audit Record" appendix of this manual for more information.

6-430

Language Statements IAF 8.0 DML

START_STREAM

START_STREAM
Syntax
START_STREAM stream_name & /TABLE=[database_handle.]table_name[,table_name[,...]][/qualifiers]

or
START_STREAM stream_name & /TABLE=#variable_name[,#variable_name[,...]][/qualifiers]

Category
Data access

Description
This statement facilitates the selection of records from one or more tables by forming a record stream. You can sequentially access records that the stream retrieves by repeatedly executing the FETCH statement. When ending a record stream, IAF executes an implicit CLEAR_BUFFER statement for the table(s) with which the stream is associated. This sets all field entries in the given streams user buffer to missing or null, except for any modified PID fields, which remain untouched. When execution of the START_STREAM statement takes place within a form, IAF places the operations completion status in the %STATUS special variable.
stream_name

This is the name that IAF is to assign to the record stream, and must uniquely identify the record stream. The FETCH statement can subsequently use the stream name that this statement specifies to identify the record stream on which the FETCH statement is to operate.
database_handle

In the first syntax above, this is the handle of the database that holds the table(s) that the /TABLE qualifier specifies. It is necessary to specify a database handle only if you have invoked multiple databases, and the current default database does not hold the table(s) that the /TABLE
Language Statements IAF 8.0 DML 6-431

START_STREAM

qualifier specifies. If present, the database handle applies to all tables that the /TABLE qualifier specifies.
table_name

In the first syntax above, this is the name of a table for which to create a record stream. All the tables that the /TABLE qualifier specifies must exist in the same database.
#variable_name

In the second syntax above, this is the name of a variable containing the name of a table for which to create the record stream. If you use a variable to specify a table for which to create the record stream, any /GROUPED_BY, /REDUCED_TO, /SORTED_BY, /STATISTIC, or /WITH qualifier that the START_STREAM statement specifies must use the context variable syntax instead of the table name syntax. For details on these syntax formats, refer to the descriptions of these qualifiers under this sections Qualifiers heading. Note that all the tables that the /TABLE qualifier specifies must exist in the same database. Also note that the first variable that the /TABLE qualifier specifies can optionally contain a database handle as part of the table name specification.

Qualifiers
The following qualifiers are valid for use with the START_STREAM statement:
/COMMIT_RATE=numeric_expression

This qualifier indicates the number of records that IAF is to process before committing the current transaction. The numeric expressions value must be an integer greater than zero. IAF commits any records that are not an integral number of the commit rate when the record stream is exhausted. For example, if a given record stream retrieves 14 records, and the commit rate that this qualifier specifies is 5, IAF commits a set of five records with the first transaction, a set of five records with the second transaction, and a set of four records with the subsequent transaction. IAF implements the /COMMIT_RATE qualifier by performing an initial selection query that stores pointers to all the records it is to process. Then, for each pointer (commit rate of one) or set of pointers (commit rate greater than one) IAF starts a transaction, processes the pointers in the set, and then commits the transaction.

6-432

Language Statements IAF 8.0 DML

START_STREAM

/FIRST=numeric_expression

This qualifier limits the number of records that the stream is to select. Note that this qualifier overrides the record selection limit that the GEM_SELECT_LIMIT System Customization Variable (SCV) specifies. For information regarding the GEM_SELECT_LIMIT SCV, refer to the IAF guide that applies to your operating system.

Examples:
/FIRST=200 /FIRST=#MAXIMUM_RECS /FIRST=(#MAXIMUM_RECS * 1.5)

/GROUPED_BY=field_name[,field_name[,...]] /GROUPED_BY=([context.]field_name[,...]) /GROUPED_BY=(#variable_name[,#variable_name[,...]])

This qualifier causes IAF to reduce the specified data to a set of records that contains unique data values in the specified fields. The GROUPED_BY qualifier maintains access to all the records in the reduced to set. This enables you to gather statistical information on all the records in the set via the /STATISTIC qualifier. The /GROUPED_BY qualifier also specifies the default sort criteria for the record stream. However, you can override the sort criteria that the /GROUPED_BY qualifier specifies by including an explicit /SORTED_BY qualifier for the given stream.

Examples:
/GROUPED_BY=DEPARTMENT

This qualifier example causes IAF to select one record for each department and return information for all records within each department.
/GROUPED_BY=(DEPARTMENT,ORDER_DATE)

This qualifier example causes IAF to select one record for each unique combination of department and order date, and return information for all records in the set. For examples of the /GROUPED_BY qualifier used in conjunction with statistical functions, refer to the description of the /STATISTIC qualifier.
/JOINED_TO=table_name

This qualifier indicates that the stream is to retrieve only records that can be joined to the specified tables record currently in the user buffer. IAF determines the join key between the first table of multiple tables specified

Language Statements IAF 8.0 DML

6-433

START_STREAM

via the /TABLE qualifier and the table that the /JOINED_TO qualifier specifies. You can use the /JOINED_TO qualifier when IAF is to process a selected master record and process any detail records that pertain to the given master record. In this type of situation, you can specify the table in which the detail records reside via the /TABLE qualifier and specify the table in which the master records reside via the /JOINED_TO qualifier. IAF automatically determines the join relationship between the two tables and appends any necessary extra selection criteria internally. Specifying the master and detail tables via the /JOINED_TO and /TABLE qualifiers, respectively, eliminates the need to specify other record selection criteria (e.g. via /WITH). This reduces coding and makes join key derivation a run-time decision, instead of a hard-coded factor.

Example:
START_STREAM DETAIL_RECORDS /TABLE=ORDER_LINES /JOINED_TO=ORDERS

This example processes a selected master record from the ORDERS table, and process the detail records in the ORDER_LINES table associated with the current ORDERS table record.
/LOCK=option_keyword

This qualifier indicates the record stream lock mode that IAF is to place on the records that the given stream retrieves. In the absence of the /LOCK qualifier, the database engine determines the default locking mechanism that the records in the given stream receive. For details regarding the default locking mechanism for a particular database engine, refer to the IAF guide that applies to that database engine. The table on the following page lists and describes the option keywords that are valid for use with the /LOCK qualifier. Option Keyword WRITE Description This option indicates that IAF is to place an immediate write lock on the records that the given stream selects. This lock mode is useful in applications that update each record that the given stream retrieves. Note that because IAF does not allow updates on multiple-table views, IAF does not apply write locks to multiple-table views.

6-434

Language Statements IAF 8.0 DML

START_STREAM

Option Keyword READ

Description This option indicates that IAF is to place an immediate read lock on the records that the given stream selects. IAF converts the READ lock to a WRITE lock only when an attempt is made to write to a record in the stream. This option indicates that IAF is to place no locks on the records that the given stream retrieves. This allows other users to update the records that the stream retrieves. However, since these updates can occur after the stream retrieves the data, it is possible that the retrieved data may not be the current data. Therefore, to maintain referential and data integrity, do not use data from a stream using the /LOCK=NONE lock mode as the basis upon which to update other records in the database.

NONE

Examples:
START_STREAM CC & /TABLE=CUSTOMERS & /WITH=DIVISION=#UPDATE_DIVISION /LOCK=WRITE

This example causes IAF to select all CUSTOMERS table records having a DIVISION field whose value is equal to the value in the #UPDATE_DIVISION variable, and place a WRITE lock on the retrieved records.
START_STREAM CC & /TABLE=CUSTOMERS & /WITH=NAME CONTAINING SMITH /LOCK=NONE

This example causes IAF to select all CUSTOMERS table records having a NAME field holding the value SMITH, but place no locks on the retrieved records.
/REDUCED_TO=(field_name[,...]) /REDUCED_TO=(table_name(field_name)[,...]) /REDUCED_TO=(context.field_name[,...]) /REDUCED_TO=(#variable_name[,...])

This qualifier ensures that the values of the specified field are unique for each record in the selected record set. IAF chooses the record that represents the reduced to set.

Language Statements IAF 8.0 DML

6-435

START_STREAM

If the START_STREAM statement specifies more than one table name via the /TABLE qualifier, a table name must prefix the names of fields from the second and subsequent tables. If the START_STREAM statement specifies the same table twice, the /REDUCED_TO qualifier can use a context variables to indicate which occurrence of the table to use. A context variable is a letter designation that IAF assigns to the specified tables, where the first table is designated A, the second table is designated B, and so on. The /REDUCED_TO qualifier can also specify a standard IAF variable (#variable in the syntax above) whose value is a field name or a field name preceded by a table name or context variable using the syntax for those formats above.

Examples:
/REDUCED_TO=(DEPARTMENT)

This qualifier example causes IAF to return information for each department only once, regardless of the number of records that exist for any given department.
/REDUCED_TO=(DEPARTMENT, SALES_ORDERS(ORDER_DATE))

This qualifier example causes IAF to return information for each sales order date within each department, only once, regardless of the number of records that exist for any given department/order date combination.
/REDUCED_TO=(B.CUSTOMER_ID)

Assuming that the CUSTOMERS table is the second table that the START_STREAM statements /TABLE qualifier specifies, this qualifier example causes IAF to return information only once for each unique CUSTOMERS(CUSTOMER_ID) value.
/REDUCED_TO=(#MEM_ID)

Assuming that the #MEM_ID variable holds the value C.MEMBER_ID, and the MEMBERS table is the third table that the START_STREAM statements /TABLE qualifier specifies, this qualifier example causes IAF to return information only once for each unique MEMBERS(MEMBER_ID) value.

6-436

Language Statements IAF 8.0 DML

START_STREAM

/SECONDARY

This qualifier indicates that the START_STREAM statement is to create a secondary stream for the table(s) that the /TABLE qualifier specifies. A secondary stream does not affect any primary or other secondary streams already active for the table(s) with which it is associated. The user buffer associated with a secondary stream is globally accessible to all forms in a limited update mode (i.e. forms cannot add or delete records, but they can modify them). For details on streams and buffers, refer to the IAF Users Guide.
/SELECTION=expression

This qualifier enables you to specify a Boolean selection statement based upon the START_STREAM statements /WITH clauses. IAF assigns each /WITH clause a letter identifier of A-Z, where the first /WITH clause is A, the second /WITH clause is B, and so on. A Boolean selection statement can use these identifiers to refer to /WITH clauses. Alternatively, a Boolean selection statement can use identifiers consisting of an asterisk (*) followed by a number, where *1 represents the first /WITH clause, *2 represents the second /WITH clause, and so on. Using identifiers of the latter type makes it possible to refer to more than 26 /WITH clauses (i.e. the limit that the alphabet imposes). A Boolean selection statement can use identifiers of all one type or can combine both types. Also, a Boolean selection statement may refer to a given /WITH clause once, more than once, or not at all.

Example:
Given a START_STREAM statement with the following /WITH clauses:
/WITH=CUSTOMER_ID=10506 /WITH=CUSTOMER_ID=10507 /WITH=ORDER_DATE=12-JAN-1998 /WITH=REQUIRED_DATE=%TODAY

a valid Boolean selection statement would be:

/SELECTION=(A OR B) AND C AND NOT D

This indicates that IAF is to select records for orders not required today, placed by customer 10506 or 10507 on 12-JAN-199.

Language Statements IAF 8.0 DML

6-437

START_STREAM

Note that in place of a Boolean selection statement, the /SELECTION qualifier can specify one of the keywords that the following table lists and describes. Option Keyword ALL Description This keyword specifies that all /WITH clauses must be true for a given record selection to take place. This is the default behavior if no /SELECTION qualifier is present. This keyword specifies that at least one /WITH clause must be true for a given record selection to take place.

ANY

/SORTED_BY=([-]field_name[,...]) /SORTED_BY=([-]table_name(field_name)[,...]) /SORTED_BY=([-]context.field_name[,...]) /SORTED_BY=([-]#variable_name[,...])

This qualifier specifies the sort order that IAF is to use for records that the START_STREAM statement selects. Specify field names in descending order of significance (i.e. sort by state then city, vs. city then state). If the START_STREAM statement specifies more than one table name via the /TABLE qualifier, a table name must prefix the names of fields from the second and subsequent tables. If the START_STREAM statement specifies the same table twice, the /SORTED_BY qualifier can use a context variables to indicate which occurrence of the table to use. A context variable is a letter designation that IAF assigns to the specified tables, where the first table is designated A, the second table is designated B, and so on. The /SORTED_BY qualifier can also specify a standard IAF variable (#variable in the syntax above) whose value is a field name or a field name preceded by a table name or context variable using the syntax for those formats on the preceding page. Preceding a given field specification by a minus sign (-) indicates that IAF is to use a descending sort order for the given field when the stream returns the selected records. By default, IAF uses an ascending sort order.

Examples:
/SORTED_BY=(DEPARTMENT)

6-438

Language Statements IAF 8.0 DML

START_STREAM

This qualifier example causes IAF to sort the streams records in ascending department order.
/SORTED_BY=(DEPARTMENT,CUSTOMERS(CUSTOMER_ID))

This qualifier example causes IAF to sort the streams records in ascending customer ID order within ascending department order.
/SORTED_BY=(ORDER_NUMBER,-ORDER_DETAILS(LINE_NUMBER))

This qualifier example causes IAF to sort the streams records in descending line number order within ascending order number order.
/SORTED_BY=(B.PART_ID,C.PART_ID)

Assuming that the PARTS table is both the second and third table that the START_STREAM statements /TABLE qualifier specifies, this qualifier example sorts the streams records in ascending component part ID order within ascending parent part ID order, where the context variable B pertains to the parent PARTS table, and C pertains to the component PARTS table.
/SORTED_BY=(#MEM_ID)

Assuming that the #MEM_ID variable holds the value C.MEMBER_ID, and the MEMBERS table is the third table that the START_STREAM statements /TABLE qualifier specifies, this qualifier example causes IAF to sort the streams records in ascending MEMBERS(MEMBER_ID) order.
/STATISTIC=#variable=AVERAGE(table_name(field_name)) /STATISTIC=#variable=COUNT /STATISTIC=#variable=MAX(table_name(field_name)) /STATISTIC=#variable=MIN(table_name(field_name)) /STATISTIC=#variable=SAMPLE_STD_DEV(table_name(field_name)) /STATISTIC=#variable=STD_DEV(table_name(field_name)) /STATISTIC=#variable=TOTAL(table_name(field_name))

This qualifier allows you to gather statistical information about records that the given stream retrieves. If the START_STREAM statement also includes the /GROUPED_BY qualifier, the specified statistic function operates only on the records that the /GROUPED_BY qualifier specifies. Otherwise, the statistic function returns information on all the records that the stream retrieves. You can append more than one statistical qualifier to a given START_STREAM statement. The table on the following page

Language Statements IAF 8.0 DML

6-439

START_STREAM

lists and describes the statistical functions that are available for use with the START_STREAM statement. Statistical Function AVERAGE(table_name(field_name)) Description This function returns the given fields average value for the given group of records. This function counts the records in the given group. This function returns the given fields maximum value for the given group of records. This function returns the given fields minimum value for the given group of records. This function returns the given fields sample standard deviation by taking the square root of the following formulas result, where n is the count of the values used, and x is the table fields value:

COUNT

MAX(table_name(field_name))

MIN(table_name(field_name))

SAMPLE_STD_DEV(table_name(field_n ame))

x ) -- n ----------------------------------------n1

(x

6-440

Language Statements IAF 8.0 DML

START_STREAM

Statistical Function STD_DEV(table_name(field_name))

Description This function returns the given fields population standard deviation by taking the square root of the following formulas result, where n is the count of the values used, and x is the table fields value:

(x
TOTAL(table_name(field_name))

x ) -- n ----------------------------------------n
2

This function returns the given fields total value for the given group of records.

The AVERAGE, SAMPLE_STD_DEV, STD_DEV, and TOTAL statistical functions operate only on fields that have a numeric native datatype or on text fields whose contents can be converted to a numeric value. These statistical functions evaluate any other field to zero. The MIN and MAX functions compare data using a fields native datatype. These statistical functions evaluate text fields as text, regardless of whether the contents of a field can be converted to a numeric value.

Example:
The following example calculates the maximum age of a customer:
START_STREAM MAX /TABLE=CUSTOMERS & /STATISTIC=#MAX_AGE=MAX(CUSTOMERS(AGE)) ! This statement creates and defines the record stream. FETCH MAX /FAILURE=(ERROR No records in CUSTOMERS) ! This statement attempts to retrieve a record from the MAX ! record stream. If it is successful, IAF places the ! maximum customer age in the #MAX_AGE variable. Other ! wise, IAF displays the error message No records in ! CUSTOMERS FETCH MAX ! This statement fails when the MAX record stream is ! exhausted. IAF terminates the stream, returns a ! failure status, and implicitly executes a CLEAR_BUFFER ! statement.

/TABLE=[database_handle.]table_name[,table_name[,...]] /TABLE=#variable_name[,#variable_name[,...]]

Language Statements IAF 8.0 DML

6-441

START_STREAM

This qualifier enables you to specify the table(s) for which the START_STREAM statement is to start a record stream. If you specify more than one table, IAF automatically determines the default join keys and joins the tables, thereby making it unnecessary to specify the join keys via /WITH qualifiers. IAF implements the /TABLE qualifier by executing the FETCH statement to retrieve the specified join table and the applicable record from the given table. The /TABLE qualifier can use a variable to specify each table on which the START_STREAM statement is to operate. The first variable that the /TABLE qualifier specifies can optionally contain a database handle as part of the table specification. As a consequence of using a variable with the /TABLE qualifier to define the table name, IAF imposes the following restrictions and conditions on the record selection process: Name checking and translation occurs at run-time, thereby possibly reducing the execution speed. IAF ignores the /CHECK qualifier when compiling record selection expressions. For information on the /CHECK qualifier, refer to this chapters discussion of the COMPILE statement. Qualifiers that specify a table name (e.g. /SORT, /REDUCED_TO, /WITH, etc.) must specify the table name via a context variable. You cannot mix variable table names and actual table names in the same record selection expression. Note that all the tables that the /TABLE qualifier specifies must reside in the same database. Therefore, if a database handle precedes the first table name (regardless of whether or not the /TABLE qualifier is using the #variable_name syntax), the database handle applies to all tables that the qualifier specifies, and not just the first table.

Examples:
START_STREAM & /TABLE=EMPLOYEES & /SORTED_BY=(DEPT_CODE) #EMP=EMPLOYEES START_STREAM & /TABLE=#EMP & /WITH=A.DEPT_CODE=01

/WITH=field_name operator expression /WITH=table_name(field_name) operator expression /WITH=context.field_name operator expression /WITH=[context.]field_name=[context.]field_name

6-442

Language Statements IAF 8.0 DML

START_STREAM

This qualifier specifies subsets of records to be included or excluded in the record selection process as dictated by the /SELECTION qualifier or lack thereof. There is no limit to the number of /WITH qualifiers that the START_STREAM statement can include. The following pages describe the /WITH qualifiers syntax components.
field_name

This is the name of the field whose data IAF is to examine. If the field comes from the second or subsequent tables of multiple tables specified via the /TABLE qualifier, you must precede the field name by a table name or a context variable indicating a table.
table_name

This is the name of table in which field to the left of the /WITH clauses operator resides. If you do not specify a table name, IAF assumes the field resides in the first table that the /TABLE qualifier specifies. If the /TABLE qualifier specifies the same table name more than once, or uses one or more variables to specify tables, the /WITH qualifier must use a context variable to indicate the name of the table in which a given field resides.
context

This is a context variable indicating the table in which a given field resides. A context variable is a letter designation (A-Z) that IAF assigns to the tables that the /TABLE qualifier specifies, where the first table that the /TABLE qualifier specifies is A, the second table is B, and so on.
operator

This is one of the operators that the following table lists and describes. Operator = <> Description Ascertain if the value to the left of the operator equals the value to the right of the operator Ascertain if the value to the left of the operator is different from the value to the right of the operator. Ascertain if the value to the left of the operator is less than or equal to the value to the right of the operator.

<=

Language Statements IAF 8.0 DML

6-443

START_STREAM

Operator >=

Description Ascertain if the value to the left of the operator is greater than or equal to the value to the right of the operator. Ascertain if the value to the left of the operator is less than the value to the right of the operator. Ascertain if the value to the left of the operator is greater than the value to the right of the operator. Ascertain if the value to the left of the operator begins with the value to the right of the operator. Ascertain if the value to the left of the operator matches the value to the right of the operator. Ascertain if the value to the left of the operator contains the value to the right of the operator. Ascertain if the value to the left of the operator matches one of the values to the right of the operator. Ascertain if the value of the table field to the left of the operator is missing.

< > STARTING WITH MATCHING CONTAINING AMONG

MISSING

Note that preceding the last five operators by the NOT operator reverses their effect.

6-444

Language Statements IAF 8.0 DML

START_STREAM

expression

This can be any valid DML expression (e.g. a literal, table field, argument, etc.). For details on using wildcard specifications in /WITH qualifier expressions, refer to the discussion of the /WITH qualifier in this manuals FORMS AND FORM QUALIFIERS chapter. Note that the MISSING operator does not require an expression. For details on missing values and date comparisons, refer to the IAF Users Guide.

Examples:
/WITH=ORDER_DATE < 15-AUG-1995

This qualifier example isolates records having an ORDER_DATE field value prior to 15-AUG-1995.
/WITH=TOTAL_VALUE > 2000.00

This qualifier example isolates records having a TOTAL_VALUE field value greater than 2000.
/WITH=BINS(PART_CODE) = PARTS(PART_CODE)

This qualifier example isolates records having a BINS(PART_CODE) field value equal to the PARTS(PART_CODE) field value in the record currently in the buffer.
/WITH=A.CUSTOMER_ID = (#AREA & 0001)

Assuming that the CUSTOMERS table is the first table that the START_STREAM statements /TABLE qualifier specifies, this qualifier example isolates CUSTOMERS table records having a CUSTOMER_ID field value equal to the value of the #AREA variable with the value, 0001, appended to it.
/WITH=CUSTOMER_ID MATCHING 10*

This qualifier example isolates records having a CUSTOMER_ID field value beginning with 10.
/WITH=DEPARTMENT AMONG 101,104,213-218,31%,4*,515,644-650

This qualifier example isolates records having a DEPARTMENT field value of 101, 104, 213 through 218, 310 through 319, 400 through 499, 515, or 644 through 650.

Examples
START_STREAM ORDERS & /TABLE=SALES_ORDERS,SALES_ORDER_LINES & /WITH=ORDER_DATE=%TODAY & /SORTED_BY=(CUSTOMER_ID) ! This statement starts the stream ORDERS, selects the

Language Statements IAF 8.0 DML

6-445

START_STREAM

! records having today as the order date, and sorts the ! records by ascending customer ID. WHILE (1) FETCH ORDERS /FAILURE=(CONTINUE OUT) ! This statement retrieves the records from the ORDERS ! stream, and upon exhausting the stream, passes control to ! the first statement following the END_WHILE statement. . . . END_WHILE START_STREAM REORDER_PARTS & /TABLE=PARTS & /WITH=QUANTITY_ON_HAND < PARTS(REORDER_LEVEL) ! This statement starts the stream REORDER_PARTS and selects ! the records having a quantity on hand less than the reorder ! level.

Related Topics
The following references contain information pertaining to the START_STREAM statement: This chapters discussion of the FETCH statement. The discussion of the %STATUS special variable in this manuals SPECIAL VARIABLES AND VALUE SYMBOLS chapter. The discussion of record selection form qualifiers in this manuals Forms and Form Qualifiers chapter. The discussions of missing values, date comparisons, record streams, transactions, and commit rates in the IAF Users Guide.

6-446

Language Statements IAF 8.0 DML

START_TRANSACTION

START_TRANSACTION
Syntax
START_TRANSACTION [READ_ONLY]

Category
Data access

Description
This statement explicitly starts a read-write transaction unless both the following conditions are true, in which case, the START_TRANSACTION statement starts a read-only transaction: The START_TRANSACTION statement includes the READ_ONLY keyword. The START_TRANSACTION statement is starting an actual transaction (not a pseudo-transaction). IAF implicitly starts a transaction under certain conditions (e.g. when executing a form that includes a /TABLE or /REPEAT qualifier, or executing a DML statement requiring database access when no transaction is in progress). Therefore, the START_TRANSACTION statement is necessary only if implicit transaction control is insufficient for the purpose at hand. Note that if an implicit transaction is active, and execution of a START_TRANSACTION statement takes place in the same form that started the implicit transaction, IAF converts the implicit transaction to an explicit transaction, does not start another transaction, and does not increment the %TRANS_LEVEL special variables value. This behavior does not apply to implicit transactions that IAF started as a result of a /TABLE qualifier or a /REPEAT qualifier on a form header statement, nor those that were started outside the form executing the START_TRANSACTION statement. In these cases, IAF does not upgrade the implicit transaction, but instead, starts a pseudo-transaction, and increments the %TRANS_LEVEL special variables value.

Example
START_TRANSACTION

Language Statements IAF 8.0 DML

6-447

START_TRANSACTION

! This statement starts an explicit read-write transaction. . START_TRANSACTION READ_ONLY ! This statement starts a pseudo read-only transaction. . START_TRANSACTION ! This statement starts a pseudo read-write transaction. . COMMIT ! This statement commits the pseudo read-write transaction without affecting the real transaction. . ROLLBACK ! This statement rolls back the pseudo read-only transaction ! without affecting the real transaction. . COMMIT ! This statement commits the changes made to the database since ! the start of the explicit transaction.

Related Topics
The following references contain information pertaining to the START_TRANSACTION statement: This chapters discussions of the COMMIT and ROLLBACK statements. The discussion of the %TRANS_LEVEL special variable in this manuals Special Variables and Value Symbols chapter. The discussions of record streams, record stream management, and transactions in the IAF Users Guide.

6-448

Language Statements IAF 8.0 DML

SWITCH

SWITCH
Syntax
SWITCH form_name [(argument1[,argument2[,...]])]

or
SWITCH form_file_spec [form_name] [(argument1[,argument2[,...]])]

Category
Program flow

Description
This statement indicates that IAF is to exit the current form and execute the specified form within the context of the form that called the current form. This statement is functionally similar to the PERFORM statement. However, the PERFORM statement causes IAF to execute the given form within the context of the current form.
NOTE:

IAF exits the form in which execution of the SWITCH statement takes place in a normal manner (i.e. IAF commits or rolls back any transaction that began within the context of the form according to the forms appropriate normal exit action).
form_file_spec

This is the file specification for either a compiled DML file (filetype .dmc) or a DML source file (filetype .dml).
form_name

This is the name of a form, which must exist within the specified form file.
argument1[,argument2[,...]]

This is one or more arguments that IAF is to pass to the specified form. IAF adheres to the following rules when preparing to pass a given argument value:

Language Statements IAF 8.0 DML

6-449

SWITCH

Single variables, table fields, and DML parameters are implicitly read-write unless enclosed in parentheses. Any other argument is read-only.

Qualifiers
/FACILITY When the /FACILITY qualifier is used, the form-name portion of a PERFORM statement must reference a facility instead of a form name. The facility is referenced using standard IAF facility syntax of:
[[database-handle.][system-name:]]facility-name

For example:
#FAC = SYS:FAC SWITCH /FACILITY #FAC (#P1,#P2,#P3)

The user must have EXECUTE access to the specified facility in order to perform the procedure. The form-file specification and form-name to be performed is taken from the facilitys menu-file and menu-form respectively. If these are blank, but the facility dml statement is not, then the facility dml statement is executed instead. In the event that the PERFORM statement specifies parameters and the facility dml is executed rather than a form, the parameters are evaluated, but not used. If the facility dml is itself a PERFORM statement, then the parameters specified on that statement are used. It is not be permitted to combine the /FACILITY qualifier with any other qualifiers (such as /BATCH).

Example
SWITCH CUSTOMER_INQUIRY

Related Topics
The following references contain information pertaining to the SWITCH statement: This chapters discussions of the SWITCH_BASE, PERFORM, COMMIT, and ROLLBACK statements. The discussions of forms and transactions in the IAF Users Guide. The discussion of forms in this manuals Forms and Form Qualifiers chapter.

6-450

Language Statements IAF 8.0 DML

SWITCH_BASE

SWITCH_BASE
Syntax
SWITCH_BASE [%EXIT]

or
SWITCH_BASE form_name [(argument1[,argument2[,...]])]

or
SWITCH_BASE form_file_spec [form_name] [(argument1[,argument2[,...]])]

Category
Program flow

Description
This statement indicates that IAF is to automatically exit the current form and execute the specified form within the context of the first form call stack form whose form header statement includes the /BASE qualifier. The SWITCH_BASE statement is functionally similar to the PERFORM statement. However, the PERFORM statement executes the specified form within the context of the current form. In contrast, the SWITCH_BASE statement indicates that IAF is to exit the current form, as well as any calling forms, until it encounters a form in the call stack whose form header statement includes the /BASE qualifier. When IAF encounters the /BASE qualifier, it executes the form that the SWITCH_BASE statement specifies within the context of the form whose form header statement includes the /BASE qualifier. Note that if you specify the SWITCH_BASE statement without arguments, IAF continues to normally process the form whose form header statement includes the /BASE qualifier. If SWITCH_BASE statement specifies the %EXIT keyword, IAF exits the form whose form header includes the /BASE qualifier with a return status of %EXIT.
NOTE:

IAF exits the form in which execution of the SWITCH_BASE statement takes place in a normal manner (i.e. IAF commits or rolls back any

Language Statements IAF 8.0 DML

6-451

SWITCH_BASE

transaction that began within the context of the form according to the forms appropriate normal exit action).

6-452

Language Statements IAF 8.0 DML

SWITCH_BASE

form_file_spec

This is the file specification for either a compiled DML file (filetype .dmc) or a DML source file (filetype .dml).
form_name

This is the name of a form, which must exist within the specified form file.

argument1[,argument2[,...]]

This is one or more arguments that IAF is to pass to the specified form. IAF adheres to the following rules when preparing to pass a given argument value: Single variables, table fields, and DML parameters are implicitly read-write unless enclosed in parentheses. Any other argument is read-only.
%EXIT

This keyword causes IAF to exit the form whose form header statement includes the /BASE qualifier with a return status of %EXIT in the %STATUS special variable.

Example
FORM MAIN /ROW=3 /COL=2 /WIDTH=78 /HEIGHT=22 /TITLE=MAIN /BASE PERFORM SUB1 PAUSE_BLOCK P1 /ROW=1 /COL=2 END_FORM FORM SUB1 /ROW=10 /COL=2 /HEIGHT=10 /WIDTH=20 /TITLE=SUB1 PERFORM SUB2 END_FORM FORM SUB2 /ROW=10 /COL=22 /HEIGHT=10 /WIDTH=20 /TITLE=SUB2 PAUSE_BLOCK P2 /ROW=1 /COL=19 SWITCH SUB3 ! This statement causes IAF to exit SUB2 and perform ! SUB3. END_FORM FORM SUB3 /ROW=10 /COL=42 /WIDTH=20 /HEIGHT=10 MENU_BLOCK MENU /ROW=1 /COL=10 & /OPT=OUT;Exit Forms, (SWITCH_BASE %EXIT) & /OPT=SUB2;Go to Form SUB2,(SWITCH SUB2) & /OPT=CONT;Continue Form MAIN, (SWITCH MAIN) END_FORM

Language Statements IAF 8.0 DML

6-453

SWITCH_BASE

Related Topics
The following references contain information pertaining to the SWITCH_BASE statement: This chapters discussions of the SWITCH, PERFORM, COMMIT, and ROLLBACK statements. The discussions of forms and transactions in the IAF Users Guide. The discussion of forms in this manuals Forms and Form Qualifiers chapter. The discussions of the %EXIT return status and the %STATUS system variable in this manuals Special Variables and Value Symbols chapter.

6-454

Language Statements IAF 8.0 DML

TABLE_SEARCH

TABLE_SEARCH
Syntax
TABLE_SEARCH [database_handle.]table_name(field_name1[,field_name2[,...]]) & [/qualifiers]

Category
Screen input and output

Description
This statement causes IAF to display data from the specified table field(s) in a List of Values (LOV) window. This statement is like the LOV functionality, except this statement does not return data from an LOV record to an input. Instead, IAF places the record in the user buffer associated with the table that the TABLE_SEARCH statement specifies. This makes the record available for subsequent use. Note that you must invoke a database prior to executing this statement. IAF performs the following actions when executing the TABLE_SEARCH statement: IAF displays a LOV window that is wide enough to contain a column for each field that the TABLE_SEARCH statement specifies. Each fields default heading displays above each column. IAF displays a data filter for each of the specified table fields. You can enter the optional wildcard characters * and % into the data filter, where * represents zero or more unknown characters, and % represents a single unknown character. This causes IAF to implicitly execute a /WITH qualifier and create record subsets according to the given criteria. If you specify one or more wildcard characters for a given fields data filter, IAF performs a matching operation for the data in the field (IAF checks the field for an exact match). Otherwise, IAF performs a starting with operation for the data in the field (IAF checks the field to see if its data starts with the indicated value). IAF displays the specified record set in the LOV window. If you do not use the data filter to reduce the record set, IAF displays all records from the specified table(s). If no records exist, IAF returns

Language Statements IAF 8.0 DML

6-455

TABLE_SEARCH

control to the data filter to enable you to perform another filter operation. You can view the records that IAF displays by using the GM_UP and GM_DOWN keys. You can press GM_BACK to exit the LOV and return to the data filter, or, you can press GM_SELECT_ROW or GM_CR to select a record from the list. Exiting the LOV via a record selection causes IAF to place the record in the user buffer. This makes the record available for subsequent program use, and exits the TABLE_SEARCH functionality.
database_handle

This is the handle for the database that holds the table whose records you wish to view. It is necessary to include a database handle only if you have invoked multiple databases, and the specified table does not reside in the default database.
table_name

This is the name of the table that holds the fields whose data you wish to view. You must specify the name of an existing table.
field_name

This is the name of a field whose data you wish to view.

Qualifiers
The following qualifiers are valid for use with the TABLE_SEARCH statement:
/BACK=(dml_statement)

This qualifier specifies the action IAF is to take if an end user presses the GM_BACK key at the first columns data filter. By default, pressing the GM_BACK key at the first columns data filter transfers control to the last previously executed input block in the form that executed the TABLE_SEARCH statement. If execution of the TABLE_SEARCH statement took place in the first block that the form executed, pressing GM_BACK at the first columns data filter causes IAF to exit the form by default. You can use the /BACK qualifier to override this behavior.
Example:
/BACK=(GOTO GET_DISC_PERCENTAGE)

6-456

Language Statements IAF 8.0 DML

TABLE_SEARCH

/COL=numeric_expression

This qualifier specifies the screen column in which IAF is to display the LOVs first column. By default, IAF displays the first column of the LOV in column two of the current form.
Example
/COL=4 /COL=(#MAX_COLS/2)

/ERROR=expression

This qualifier specifies the user-defined error message that IAF is to display if it finds no records that match the given search criteria.
Example:
/ERROR=No matching records.

/EXIT=(dml_statement)

This qualifier specifies the action IAF is to take if an end user presses GM_EXIT at the first columns data filter. By default, IAF exits the form in which the block resides. You can use the /EXIT qualifier to override this behavior.
Example:
/EXIT=(CONTINUE ROLLBACK)

/FIRST=numeric_expression

This qualifier limits the number of records that the TABLE_SEARCH statement is to display in the LOV window. Note that this qualifier overrides the record selection limit that the GEM_SELECT_LIMIT System Customization Variable (SCV) specifies. For information regarding the GEM_SELECT_LIMIT SCV, refer to the IAF guide that applies to your operating system.
Examples:
/FIRST=200 /FIRST=#MAXIMUM_RECS /FIRST=(#MAXIMUM_RECS * 1.5)

/HEIGHT=numeric_expression

This qualifier specifies the number of rows the LOV window is to display. By default, IAF uses a height of ten for the LOV window.
Examples:
/HEIGHT=19

Language Statements IAF 8.0 DML

6-457

TABLE_SEARCH

/HEIGHT=(#MAX_HEIGHTS/2)

6-458

Language Statements IAF 8.0 DML

TABLE_SEARCH

/NOERROR

This qualifier disables the default error message that IAF is to display if it does not find any records that match the data criteria that the data filter specifies. By default, IAF displays a system-defined error message and returns the end user to the data filter upon finding no records that match the data filter specifications. The /NOERROR qualifier is useful if you wish to substitute a user-defined error message for the default system defined message.
/REDUCED_TO=(field_name[,...]) /REDUCED_TO=(table_name(field_name)[,...]) /REDUCED_TO=(#variable_name[,...])

This qualifier ensures that the values of the specified field are unique for each record in the LOV record set. IAF chooses the record that represents the reduced to set. The /REDUCED_TO qualifier can specify a field name, a field name preceded by a table name, or a standard IAF variable (#variable in the syntax above) whose value is a field name or a field name preceded by a table name.
Examples:
/REDUCED_TO=(DEPARTMENT)

This qualifier example causes IAF to return information for each department only once, regardless of the number of records that exist for any given department.
/REDUCED_TO=(DEPARTMENT, SALES_ORDERS(ORDER_DATE))

This qualifier example causes IAF to return information for each sales order date within each department, only once, regardless of the the number of records that exist for any given department/order date combination.
/REDUCED_TO=(#MEM_ID)

Assuming that the #MEM_ID variable holds the value MEMBER_ID, this qualifier example causes IAF to return information only once for each unique MEMBER_ID value.
/ROW=numeric_expression

This qualifier specifies the screen row on which IAF is to display row one of the LOV window. If the TABLE_SEARCH statement does not include

Language Statements IAF 8.0 DML

6-459

TABLE_SEARCH

this qualifier, IAF displays row one of the LOV window in row two of the form that executes the TABLE_SEARCH statement.
Examples:
/ROW=3 /ROW=(#MAX_ROWS/2)

/SELECTION=expression

This qualifier enables you to specify a Boolean selection statement based upon the TABLE_SEARCH statements /WITH clauses. IAF assigns each /WITH clause a letter identifier of A-Z, where the first /WITH clause is A, the second /WITH clause is B, and so on. A Boolean selection statement can use these identifiers to refer to /WITH clauses. Alternatively, a Boolean selection statement can use identifiers consisting of an asterisk (*) followed by a number, where *1 represents the first /WITH clause, *2 represents the second /WITH clause, and so on. Using identifiers of the latter type makes it possible to refer to more than 26 /WITH clauses (i.e. the limit that the alphabet imposes). A Boolean selection statement can use identifiers of all one type or can combine both types. Also, a Boolean selection statement may refer to a given /WITH clause once, more than once, or not at all.
Example:

Given a TABLE_SEARCH statement with the following /WITH clauses:

/WITH=CUSTOMER_ID=10506 /WITH=CUSTOMER_ID=10507 /WITH=ORDER_DATE=12-JAN-1995 /WITH=REQUIRED_DATE=%TODAY

a valid Boolean selection statement would be:

/SELECTION=(A OR B) AND C AND NOT D

This indicates that IAF is to select records for orders not required today, placed by customer 10506 or 10507 on 12-JAN-1995.

6-460

Language Statements IAF 8.0 DML

TABLE_SEARCH

Note that in place of a Boolean selection statement, the /SELECTION qualifier can specify one of the keywords that the table on the following page lists and describes. Option Keyword ALL Description This keyword specifies that all /WITH clauses must be true for a given record selection to take place. This is the default behavior if no /SELECTION qualifier is present. This keyword specifies that at least one /WITH clause must be true for a given record selection to take place.

ANY

/SELECT_ONE

This qualifier causes the TABLE_SEARCH to exit immediately, without returning to the data filter, if IAF finds only one record that matches the criteria that the data filter specifies. IAF does not display the single record, but does place the record in the user buffer.
/SORTED_BY=([-]field_name[,...]) /SORTED_BY=([-]table_name(field_name)[,...]) /SORTED_BY=([-]#variable_name[,...])

This qualifier specifies the sort order that IAF is to use for records that the TABLE_SEARCH statement selects. Specify field names in descending order of significance (i.e. sort by state then city, vs. city then state). The /SORTED_BY qualifier can specify a field name, a field name preceded by a table name, or a standard IAF variable (#variable in the syntax above) whose value is a field name or a field name preceded by a table name. Preceding a given field specification by a minus sign (-) indicates that IAF is to use a descending order for the given field when returning the selected records. By default, IAF uses an ascending order.
Examples:
/SORTED_BY=(DEPARTMENT)

This qualifier example causes IAF to sort the streams records in ascending department order.

Language Statements IAF 8.0 DML

6-461

TABLE_SEARCH

/SORTED_BY=(DEPARTMENT,CUSTOMERS(CUSTOMER_ID))

This qualifier example causes IAF to sort the streams records in ascending customer ID order within ascending department order.
/SORTED_BY=(ORDER_NUMBER,-ORDER_DETAILS(LINE_NUMBER))

This qualifier example causes IAF to sort the streams records in descending line number order within ascending order number order.
/SORTED_BY=(#MEM_ID)

Assuming that the #MEM_ID variable holds the value MEMBER_ID, this qualifier example causes IAF to sort the streams records in ascending MEMBER_ID order.
/WITH=field_name operator expression

This qualifier enables you to search for a subset of the record set in the specified table. There is no limit to the number of /WITH qualifiers you can append to the TABLE_SEARCH statement.
field_name

This is the name of the field whose data IAF is to examine as part of the subsetting process. Note that it is not necessary to specify a field that the TABLE_SEARCH statement specifies as part of its syntax. However, the the field that the /WITH qualifier specifies must reside in the table that the TABLE_SEARCH statement specifies.
operator

The operators that the following table lists and describes are valid for use with the /WITH qualifier. Operator = <> <= Description Ascertain if the value to the left of the operator equals the value to the right of the operator Ascertain if the value to the left of the operator is different from the value to the right of the operator. Ascertain if the value to the left of the operator is less than or equal to the value to the right of the operator. Ascertain if the value to the left of the operator is greater than or equal to the value to the right of the operator.

>=

6-462

Language Statements IAF 8.0 DML

TABLE_SEARCH

Operator < > STARTING WITH MATCHING CONTAINING AMONG

Description Ascertain if the value to the left of the operator is less than the value to the right of the operator. Ascertain if the value to the left of the operator is greater than the value to the right of the operator. Ascertain if the value to the left of the operator begins with the value to the right of the operator. Ascertain if the value to the left of the operator matches the value to the right of the operator. Ascertain if the value to the left of the operator contains the value to the right of the operator. Ascertain if the value to the left of the operator matches one of the values to the right of the operator. Ascertain if the value of the table field to the left of the operator is missing.

MISSING

Note that preceding the last five operators by the NOT operator reverses their effect.
expression

This can be any valid DML expression such as a literal, table field, or parameter.
Examples:
/WITH=ORDER_DATE = 12-MAR-1995 /WITH=TOTAL_VALUE = 20000.00 /WITH=PART_CODE = PARTS(PART_CODE) /WITH=CUSTOMER_ID MATCHING 10* /WITH=DEPARTMENT AMONG 101,213-218,31%,4*,515,644-650

Example
TABLE_SEARCH PARTS (WAREHOUSE_CODE,PART_CODE,NAME) & /ROW=6 /COL=12 & /EXIT=(EXIT) & /BACK=(GOTO CONFIRM) & /WITH=QUANTITY_ON_HAND <> 0.00 & /SELECT_ONE

Related Topics
The following reference contain information pertaining to the TABLE_SEARCH statement:

Language Statements IAF 8.0 DML

6-463

TABLE_SEARCH

The discussion of list of values functionality in the IAF Conventions Guide.

6-464

Language Statements IAF 8.0 DML

TRANSFER

TRANSFER
Syntax
TRANSFER command_filename

Category
Miscellaneous

Description
This statement enables you to invoke the Transfer utility and transfer a flat file into the currently active database. The TRANSFER statement causes IAF to read a language-based command file (i.e. a description file) that contains the layout of the flat file you wish to transfer and the commands that instruct IAF to transfer the file to the current database. You must create the command description file prior to executing the TRANSFER statement. Note that during the transfer, IAF commits a transaction for every 1,000 records it transfers.
command_filename

This is the name of a description file that contains the commands that instruct IAF how to transfer the flat file. The description file contains the name of the file to transfer, a data transfer option keyword, the database table specification indicating the target of the transfer, a description of the flat file layout, data assignments, and any applicable comments. Following are descriptions of the components that a transfer command description file can include.
Filename Syntax
FILENAME=flat_filename

Description

This declaration specifies the name of the flat file from which IAF is to read the data to transfer. The filename must be a valid file specification. You can specify only one FILENAME statement per description file.

Language Statements IAF 8.0 DML

6-465

TRANSFER

Options Syntax
OPTIONS STATUS

Description

The OPTIONS command specifies the additional transfer operations that IAF is to execute. Currently, you can include the STATUS option to cause IAF to display a status box while executing the TRANSFER statement.
Table Syntax
TABLE table_name [mode]

Description

This command specifies the table to which IAF is to write the transferred data. Specifying an invalid table name causes IAF to display an error message. You can include any number of TABLE statements in a given description file. This indicates that IAF is to simultaneously update multiple tables from a single flat file. The following table lists and describes the update modes that are valid for use with the TABLE command. Mode UPDATE Description This update mode causes the transfer utility to search for records with the given PID value, and update the records non-PID fields. This update mode causes the transfer utility to search for a record with the given PID value, and, if present, update the record. Otherwise, this update mode causes the transfer utility to add the record with the specified PID value. This update mode causes the transfer utility to add a record. If the transfer utility finds a record with the given PID value, it neither updates nor adds the record.

MERGE

APPEND

If you do not specify a mode, IAF uses MERGE mode.

6-466

Language Statements IAF 8.0 DML

TRANSFER

Define Syntax
DEFINE field_name [/qualifiers]

Description

This command enables you to describe the layout of the records in the flat file. Each DEFINE statement describes a field.
Qualifiers
/DATATYPE=datatype

The datatype specifies the type of data that the TRANSFER utility is to read from the given flat file field. Placing a U before the datatype indicates that the given data is unsigned. The following table lists the datatypes that are valid for use with this qualifier. BYTE, UBYTE D_FLOAT DATE_TIME F_FLOAT G_FLOAT LONGWORD,ULONGWO RD NL NLO NR NRO NU Numtext NZ PACKED QUADWORD, UQUADWORD TEXT VARYING_STRING WORD,UWORD

The following table lists the available string date datatypes. YYMMDD MMDDYY DDMMYY YYYYMMDD MMDDYYYY DDMMYYYY

Note that an invalid date causes IAF to write an error to the transfer log file and store a zero date/time in the field. An example transfer log file is reproduced at the end of this section.

Language Statements IAF 8.0 DML

6-467

TRANSFER

If you define a text field that contains a date in one of the date datatype formats, IAF can directly transfer the data to a standard date/time field. If the date stores the year as two characters, IAF assumes the date is in the 20th century (i.e. 01-Jan-1900 to 31-Dec-1999).
/POSITION=position

This qualifier specifies the starting position of the field. The position must be an integer whose value falls within the range of one to the length of the record.
/LENGTH=length

This qualifier specifies the number of bytes in the field and is necessary for NL, NLO, NR, NRO, NZ, NU, PACKED, NUMTEXT, and TEXT, data.
/SCALE=scale

This qualifier specifies an implied scale factor for integer datatype fields. A scale of -2 indicates that IAF is to divide the field data by 100 to obtain the actual value stored in the database field.
Data Assignments Syntax
table_name(field_name)=field_definition

or
table_name(field_name)=quoted_literal

or
(field_name)=keyword

Description

These assignments each assign a value to a table field. The given table field must exist within the current database. The field definition is the name given to a portion of the flat file record and must already have been defined via the DEFINE command. It is advisable to write a value to all the PID fields for the given table. If you specify a quoted literal as the source, you can use either single or double quotes to delimit the text. However, IAF requires consistency in their use (i.e. a single quote must be paired with a single quote, and a double quote must be paired with a double quote). Note that you must enclose numeric literals in quotes. The

6-468

Language Statements IAF 8.0 DML

TRANSFER

table on the following page lists the keywords that are valid for use in assignments. Keywor d %NOW %TODA Y %SEQU ENCE The current date and time. The current date. A sequence number for the given record, relative to the flat file. You can use the sequence number to sort the records in the IAF table into the same order as the records in the flat file. Value

Comments Syntax
!comment_text

Description

A comment is descriptive text that begins with an exclamation mark (!).

Example Transfer File
[Top of File] FILENAME=cust_m.dat ! Specify the flat file. TABLE CUSTOMERS APPEND ! Add only new customers that dont already exist. DEFINE CUST_ID /POSITION=1 /LENGTH=6 /DATATYPE=TEXT DEFINE NAME /POSITION=7 /LENGTH=30 /DATATYPE=TEXT DEFINE BALANCE /POSITION=60 /DATATYPE=LONGWORD ! Define the field layout. CUSTOMERS(CUSTOMER_ID)=CUST_ID CUSTOMERS(CUSTOMER_NAME)=NAME CUSTOMERS(CUSTOMER_BALANCE)=BALANCE ! Define the assignments for each record. [End of File]

Language Statements IAF 8.0 DML

6-469

TRANSFER

Example Transfer Log File

When executing the TRANSFER statement, IAF produces a transfer log file (transfer.log) as the following example illustrates:
[Top of File] Log File for processing of : cust_m.dat on 9-SEP-1998 16:48:04.34 Table Names Used CUSTOMERS Targets for assignments Table CUSTOMERS FieldCUSTOMER_IDEntry 1 Table CUSTOMERS FieldCUSTOMER_NAMEEntry 2 Table CUSTOMERS FieldCUSTOMER_BALANCEEntry 3 Sources For Assignments Name CUST_ID length 6 position 1 datatype TEXT Name NAME length 30 position 7 datatype TEXT Name BALANCE length 0 position 60 datatype LONGWORD Error occurred on record 1 Text
%TXRMAN-E-RECEXISTS, Data already exists - not overwritten (line )

End of log file : 2 records processed [End of File]

Related Topics
The following references contain information pertaining to the TRANSFER statement: The discussion of fields in the IAF guide that applies to your database engine. The discussion of dates in the IAF Users Guide.

6-470

Language Statements IAF 8.0 DML

TRIGGER

TRIGGER
Syntax
TRIGGER trigger_name

Category
Utilities and program development

Description
This statement executes the DML code associated with the given time trigger and facilitates testing time triggers from the IAF command line prompt (GEM> by default).

Example
TRIGGER CUSTOMERS_UPDATE

Related Topics
The following reference contains information pertaining to the TRIGGER statement: The discussion of time triggers in the IAF Users Guide and the IAF System Reference Manual.

Language Statements IAF 8.0 DML

6-471

UNLOAD

UNLOAD
Syntax
UNLOAD file_spec FROM [database_handle.]table_name(field_name)

Category
Data access

Description
This statement causes IAF to unload a documentary field into a file. You can specify the file via a file specification without quotes, a quoted string indicating the file specification, or a file specification in a variable. The data in the file can only be a simple text. This means that you cannot extract proprietary formatted data, such as word processing information, a spreadsheet data, or even graphical images, from segmented string fields within the database.

Examples
UNLOAD filename.txt FROM EMPLOYEES(RESUME) UNLOAD #FILE FROM EMP.EMPLOYEES(COMMENTS)

Related Topics
The following reference contains information pertaining to the UNLOAD statement: This chapters discussion of the LOAD statement.

6-472

Language Statements IAF 8.0 DML

UTILITIES

UTILITIES
Syntax
UTILITIES

Category
Utilities and program development

Description
This statement invokes the main Utilities menu. This menu contains options that enable you to invoke IAFs generators and editors, and perform forms. You can invoke the main utilities menu by executing the UTILITIES statement at the IAF command line prompt (GEM> by default).

Related Topics
The following references contain information pertaining to the UTILITIES statement: This chapters discussions of the EDIT/DICTIONARY, EDIT/FORMS, EDIT/REPORTS, EDIT/SECURITY, EDIT/SYSTEM, EDIT/TABLE, FILES, GENERATE/FORMS, and GENERATE/REPORTS statements. The discussion of IAFs editors and generators in the IAF System Reference Manual.

Language Statements IAF 8.0 DML

6-473

VERIFY

VERIFY
Syntax
MSSQL Server Engine:
VERIFY user-name/password/database-name@DNSName /ENGINE=MSSQL /MAX_ERRORS=[Number of errors] /OUTPUT=GEM_RUN:[File_name]

ORACLE Server Engine:

VERIFY user-name/password/schema@Connection_String /ENGINE=ORACLE /MAX_ERRORS=[Number of errors] /OUTPUT=GEM_RUN:[File_name]

Category
Utilities and program development

Description
This command is fully documented under the Database Integrity Checker description. It has been developed like an involk command.

Qualifiers
/ENGINE Currently supports MSSQL and ORACLE /MAX_ERRORS Maximum number of errors to be displayed. If omitted, a value of 100 is assumed. /OUTPUT Specifies the file where the error messages will be saved. If omitted, only the error messages on the screen will display.

6-474

Language Statements IAF 8.0 DML

WHILE and END_WHILE

WHILE and END_WHILE

Syntax
WHILE (condition_expression) dml_statement

or
WHILE (condition_expression) dml_code END_WHILE

Category
Program flow

Description
This set of language constructs enables you to specify a conditional expression for IAF to evaluate to determine whether or not to execute a single statement (simple WHILE), or multiple statements (compound WHILE). The given DML code executes as a loop as long as the conditional expression evaluates to TRUE. If the conditional expression evaluates to FALSE, IAF does not execute the statement(s). You can nest WHILE statements within a given WHILE/END_WHILE construct. You can include the CONTINUE statement within a compound WHILE statement. The CONTINUE statement causes IAF to branch to the END_WHILE statement and continue with the next iteration of the loop. Note that the CONTINUE OUT statement causes program control to transfer to the statement immediately following the END_WHILE statement, thereby exiting the loop. Compound WHILE statements may span blocks (i.e. the WHILE statement can execute in one block and the END_WHILE execute in a subsequent block).

Language Statements IAF 8.0 DML

6-475

WHILE and END_WHILE

condition_expression

This is an expression that IAF evaluates to TRUE or FALSE according to the following rules: Value Numeric and non-zero Numeric and zero String beginning with Y or y String beginning with T or t Anything else TRUE/FALSE Evaluation TRUE FALSE TRUE TRUE FALSE

Examples
WHILE (LEN(#UNDER_SCORES) <10) & #UNDER_SCORES=#UNDERSCORES & _ WHILE (#COUNT=100) FETCH CUSTOMERS/FAILURE=(CONTINUE OUT) #TOTAL_SALES=#TOTAL_SALES + CUSTOMERS(TOTAL_SALES) #COUNT=#COUNT + 1 END_WHILE

Related Topics
The following reference contains information pertaining to the WHILE and END_WHILE statements: This chapters discussion of the CONTINUE statement. This chapters discussion of the IF, ELSE_IF, ELSE, and END_IF statements.

6-476

Language Statements IAF 8.0 DML

WRITE

WRITE
Syntax
WRITE tag data

Category
Text file management

Description
This statement enables you to write data into the record buffer associated with the given file. Note that IAF writes the record when it executes a WRITE_LINE statement.
tag

This is the handle for the text file to whose record buffer IAF is to write, and is the handle that the OPEN_TEXT statement specified to open the given file.
data

This is the data IAF is to write to record and can be any valid expression. Note that IAF appends the data that this argument specifies to any data currently in the buffer as a result of a previously executed WRITE statement.

Example
WRITE ADDRESS #CURR_ADDRESS

Related Topics
The following reference contains information pertaining to the WRITE statement: This chapters discussions of the OPEN_TEXT, CLOSE_TEXT, READ_LINE, and WRITE_LINE statements.

Language Statements IAF 8.0 DML

6-477

WRITE_LINE

WRITE_LINE
Syntax
WRITE_LINE tag [data]

Category
Text file management

Description
This statement causes IAF to write a record to the given text file. You can use this statement independently of the WRITE statement to write records to the given text file.
tag

This is the handle for the text file to which IAF is to write, and is the handle that the OPEN_TEXT statement specified to open the given file.
[data]

This is the data IAF is to write to the record and can be any valid expression. This argument causes IAF to append the specified data to the data currently in the record buffer as a result of a previously executed WRITE statement (if any), prior to writing the buffer. After writing the buffer to the given text file, IAF clears the buffer.

Examples
WRITE_LINE ADDRESS WRITE_LINE NAME #CUST_NAME

Related Topics
The following references contain information pertaining to the WRITE_LINE statement: This chapters discussions of the OPEN_TEXT, CLOSE_TEXT, READ_LINE, and WRITE statements.

6-478

Language Statements IAF 8.0 DML

XML_RECEIVE_TABLES

XML_RECEIVE_TABLES
Syntax
XML_RECEIVE_TABLES [/ERROR_TEXT=error-text]

Category
Client/Server environment.

Description
The XML_RECEIVE_TABLES statement receives a stream of XML tables from the Connect client. The XML_RECEIVE_TABLES statement is only valid for use in stored procedures that are executed by Connect clients. Please see the Connect User Guide for more information. At present, the XML_RECEIVE_TABLES statement should only be used for virtual tables. The reason for this is that the procedure empties all the contents of the table prior to receiving the new table data from the client. The stored procedure issuing the call can perform further data manipulations and/or move the received data from the virtual table to physical tables as desired after the data transfer is completed.

Qualifiers
/ERROR_TEXT=error-text

Any error condition encountered by the XML parser is returned to the caller in the target destination specified with the /ERROR_TEXT qualifier.

Examples
The following example illustrates proper usage from within a DML stored procedure.
XML_RECEIVE_TABLES /ERROR_TEXT=#Error_Text

Language Statements IAF 8.0 DML

6-479

XML_RECEIVE_TABLES

Assuming for this example that the stored procedure expects data for the VT_XML_DEMO virtual table, the data can subsequently be moved to the XML_DEMO physical table after the data transfer is completed:
XML_DEMO(FIELD1) = VT_XML_DEMO(FIELD1) XML_DEMO(FIELD2) = VT_XML_DEMO(FIELD2) XML_DEMO(FIELD3) = VT_XML_DEMO(FIELD3) ADD TO XML_DEMO

Related Topics
See also the XML_RECEIVE_TABLES, XML_RECEIVE_TEXT and XML_SEND_TEXT statements. Please refer to the Connect User Guide for more information concerning the Connect product.

6-480

Language Statements IAF 8.0 DML

XML_SEND_TABLE

XML_SEND_TABLE
Syntax
XML_SEND_TABLE table-name & [/TABLE_OPTIONS=table-options] & [/FIELD_OPTIONS=field-options]

Category
Client/Server environment.

Description
This statement packages a table as an XML stream and sends the XML to the Connect client. The XML_SEND_TABLE statement is only valid for use in stored procedures that are executed by Connect clients. Please see the Connect User Guide for more information.
table-name

The name of the table to send.

Language Statements IAF 8.0 DML

6-481

XML_SEND_TABLE

Qualifiers
The following qualifiers are valid for use with the XML_SEND_TABLE statement:
/TABLE_OPTIONS=table-options

This qualifier indicates the desired table data and metadata to send. The table options are specified as a string containing a comma separated list of options. The available table options are:

Keyword [NO]ALL [NO]DATA [NO]NAME [NO]DESCRIPTION [NO]VIRTUAL

XML Tags All tags or table tags only. <data></data> <tablename></tablename> <description></description> <virtual><persistent></persistent></virtual>

/FIELD_OPTIONS=field-options

This qualifier indicates the desired table-field metadata to send. The field options are specified as a string containing a comma separated list of options. The available field options are:

Keyword [NO]ALL

XML Tags All field metadata tags or no field metadata tags. [NO]DATA_TYPE <datatype></datatype> [NO]INPUT_MASK <inputmask></inputmask> [NO]OUTPUT_MASK <outputmask></outputmask> [NO]MISSING <missing></missing> [NO]INITIAL_VALUE <initialvalue></initialvalue> [NO]COMPUTED_SOURCE<computedsource></computedsource> [NO]VALID_VALUES <validvalues></validvalues> [NO]DESCRIPTION <description></description> [NO]NUMBER <number></number> [NO]LENGTH <nativelength></nativelength> and <baselength></baselength> [NO]SCALE <scale></scale>

6-482

Language Statements IAF 8.0 DML

XML_SEND_TABLE

Keyword [NO]PROMPT [NO]SHORT_PROMPT [NO]HEADING [NO]FLAGS [NO]DEFAULT [NO]INPUT_LENGTH [NO]OUTPUT_LENGTH [NO]XML_FORMAT

XML Tags <prompt></prompt> <shortprompt></shortprompt> <heading></heading> <flags></flags> <default></default> <inputlength></inputlength> <outputlength></outputlength> <xmlformat></xmlformat>

Examples
DML EXAMPLE #1
The following example illustrates proper usage from within a DML stored procedure:
XML_SEND_TABLE VRT_ORDERS & /TABLE_OPTIONS="ALL" & /FIELD_OPTIONS=("NOALL,NAME,DATA_TYPE," & "INPUT_MASK,OUTPUT_MASK,MISSING," & "INITIAL_VALUE,COMPUTED_SOURCE," & "VALID_VALUES,DESCRIPTION," & "NUMBER,LENGTH,SCALE,PROMPT")

Assuming that the VRT_ORDERS3 table contains no data, the following output is produced:
<table name="VRT_ORDERS3"> <metadata> <field> <prompt>field 1 prompt</prompt> </field> <field> <prompt>field 2 prompt</prompt> </field> </metadata> <data> </data> </table>

Language Statements IAF 8.0 DML

6-483

XML_SEND_TABLE

DML EXAMPLE #2
This example shows how multiple tables can be sent in the XML stream to the client. The sample sends two tables by coding two XML_SEND_TABLE statements:
XML_SEND_TABLE RENTALS & /TABLE_OPTIONS="NOALL,DATA" & /FIELD_OPTIONS="NOALL" XML_SEND_TABLE STATUS_MESSAGES_VT & /TABLE_OPTIONS="NOALL,DATA" & /FIELD_OPTIONS="NOALL"

Because the TABLE_OPTIONS qualifier specifies "NOALL,DATA" for both calls, only table data is sent to the client. The sample XML does not contain any <metadata> tags:
<table name="RENTALS"> <data> <row>...</row> <row>...</row> </data> </table> <table name="STATUS_MESSAGES_VT"> <data> <row>...</row> <row>...</row> </data> </table>

Related Topics
See also the XML_RECEIVE_TABLE, XML_RECEIVE_TEXT and XML_SEND_TEXT statements. Please refer to the Connect User Guide for more information concerning the Connect product.

6-484

Language Statements IAF 8.0 DML

$
Syntax
$ operating_system_command

Category
Miscellaneous

Description
This statement enables you to execute operating system commands from within IAF. For details regarding this statement, refer to the IAF guide that applies to your operating system. When execution of the $ statement takes place within a form, IAF places the operations completion status in the %STATUS special variable.

Related Topics
The following references contain information pertaining to the $ statement: This chapters discussion of the CLI statement. The discussion of the %STATUS special variable in this manuals Special Variables and Value Symbols chapter. The discussion of the $ statement in the IAF guide that applies to your operating system.

Language Statements IAF 8.0 DML

6-485

Chapter 7

Expressions

Data Elements

An expression is a single data element, or one or more data elements and one or more operators that evaluate to a single value. This chapter describes the data elements and operators that can comprise an expression that is valid for generic use within IAF. Note that individual language statements and constructs may support operators in addition to those that this chapter discusses. For details regarding the operators that a given language statement or construct supports, refer to its description in this manual.

Data Elements
Literals
Literals are constant values that can be string values (text), integers (numeric), or floating point numbers (numeric). Text literals must be enclosed in single or double quotes. Floating point numbers can be in standard floating point format or exponential format. The following table provides examples of each literal type. Literal Type string Examples Customer name: ORDER_ENTRY Y integer constant -123 55 0

7-2

Expressions IAF 8.0 DML

Data Elements

Literal Type floating point numeric

Examples [-]nE[+-]n An optional leading minus sign followed by one or more decimal digits followed by an exponent. [-][n].n[E[+-]n] An optional leading minus sign followed by one or more optional decimal digits followed by a decimal point and one or more decimal digits followed by an optional exponent. [-]n.[n][E[+-]n] An optional leading minus sign followed by one or decimal digits followed by a decimal point and one or more optional decimal digits followed by an optional exponent.

Notes About Numeric Literals

In each of the three above formats, the following restrictions are imposed: The only leading sign character allowed is the minus sign (-). A leading plus sign (+) is not allowed. If a decimal point (.) is present, the number must have at least one digit present on at least one side of the decimal point. (That is why formats 2 and 3 are presented separately.) For example 0., .0, and 0.0 are all legal, but just plain . is not. This is the case regardless of whether or not an optional leading sign precedes and/or an optional exponent follows. The exponent portion consists of the character E or e followed by an optional plus (+) or minus (-) sign, followed by one or more decimal digits. One or more decimal digits MUST follow the exponent character (the E or e character). An E or e character by itself without any following decimal digits is not allowed. For example, 1.2e0 is legal, but 1.2e is not. The exponent value is limited to five decimal digits and an absolute range of 99,999 to +99,999.

Expressions IAF 8.0 DML

7-3

Data Elements

If more than 86 total digits (sum of digits on each side of the decimal point) are present; the number is rounded to 86 significant digits. If neither a decimal point nor an exponent is present, then the number is an integer rather than floating point (see below). This is upward compatible with previous IAF versions. The syntax diagram for an integer numeric literal remains the same with the exception that much larger numbers may be used. (Square brackets denote optional components.) [-]n An optional leading minus (-) sign followed by one or more decimal digits. If more than 86 decimal digits are present; the number is rounded to 86 significant digits. No decimal point or exponent is allowed. If a decimal point or exponent is encountered, then the number is floating point (see above). Note: Numeric qualifier arguments are not numeric literals in the same sense that regular numeric literals are. Qualifier arguments are generally limited to small (32-bit integer or less) values, generally dont allow decimal points or exponents, and are generally not involved in arithmetic operations. The extended precision enhancements made in IAF V6.1 have no effect on current syntax, range, precision, or other behavior of most qualifier arguments. The type object that is being assigned to the numeric qualifier is significant. For instance, numeric qualifier values specified by variables, for example /BEGIN_ROW=#BR, are limited to values that can be represented by 32-bit integers (i.e. up to 2,147,483,647). Numeric qualifier values specified by numeric literals, for example /BEGIN_ROW=9999 are limited to values that can be represented by 16bit integers (i.e. up to 32,767), as that is the limit for numeric literals. The prior 31-digit limitation on the length of unquoted floating- point numeric literals has been lifted. Unquoted numeric literals may now be of any length. However, all numeric literals, quoted or not, are rounded to 86 significant decimal digits. The prior floating point literal exponent range restriction of E-128 to E+127 has been lifted. The floating-point literal exponent range is now E-99999 to E+99999.

7-4

Expressions IAF 8.0 DML

Data Elements

Some examples of floating-point literals which were previously allowed and are now disallowed in version 6.0 are as follows:

Both integer and fraction digits missing:

., -., E, .E, -.E, E-, .E-, -.E-, En, .En, -.En, E-n, .E-n, -.E-n

Exponent digits missing:

nE, -nE, nE-, -nE-, n.E, -n.E, n.E-, -n.E-, .nE, -.nE, .nE-, -.nE-

Note: n above represents one or more digits. E above is an upper or lower case letter E.

Table Fields
A table field specification identifies the occurrence of a given field in a given table, and may have one of the following formats:
[stream_name:]table_name(i) [database_handle.]table_name(field_name)

where stream_name is the name of a stream associated with the given table, and database_handle is the handle for the database in which the given table field resides. Prefixing a table field specification with a stream name is applicable only when a FIND or START_STREAM statement creates a secondary stream, and a record is currently available in the given stream. Prefixing a table field specification with a database handle is necessary only if you have invoked multiple databases, and the specified table does not reside in the default database. You can use a table field specification as part of an expression or as part of an assignment statement. For details regarding assignment statements, refer to this manuals overview. For details regarding the FIND and START_STREAM statements, refer to this manuals Language Statements chapter. For details regarding streams, refer to the IAF Users Guide. Database handles and stream names are mutually exclusive specifications because a streams definition includes a database declaration. Therefore, specifying a database handle with a stream name would be redundant.

Expressions IAF 8.0 DML

7-5

Data Elements

Examples:
PARENT:PARTS(PART_CODE) VIDEOS.RENTALS(MOVIE_ID) MEMBERS(MEMBER_ID)

7-6

Expressions IAF 8.0 DML

Data Elements

Computed Fields
IAF allows you only to read from a computed field, unless it is a concatenation of fixed length text fields. To write to a computed field of this type, IAF splits the input string into its component lengths and writes to each field separately.

Variables
A variable identifier is a hash sign (#) followed by a name which must be a valid symbol, consisting of letters (A-Z), numbers (0-9), and underscores (_), and must be no longer than 31 characters. The first character following the hash sign (#) in a variable name must be a letter. A variable name can also include the dollar sign ($). However, a variable name cannot begin or end with a dollar sign. Variables are global to the compilation unit (i.e. file) in which they occur unless you declare a variable as an argument in a form header statement, in which case, the variable is local to the given form.

Examples
Following are examples of valid variable names:
#A #TOTAL_VALUE #RUN$FLAG

Following are examples of invalid variable names:

TOTAL_COST

This variable name is missing the mandatory leading hash sign (#).
#PART.CODE

This variable name contains a period (.), which is not a valid character for a variable name.
#COMPLETE_PROJECT_COST_OVERRUN_VALUE

This variable name contains more than the maximum number of characters allowed for variable names (for example; 31).

Expressions IAF 8.0 DML

7-7

Data Elements

Special Variables
Expressions can also contain special variables, which are variables to which IAF assigns values. Special variable names begin with a percent sign (%). For details regarding special variables, refer to this manuals Special Variables And Value Symbols chapter.

Arrays
An array specification identifies the occurrence of a given element of a given array, and may have the following format:
#array_name(numeric_expression)

An array identifier consists of a hash (#) sign followed by a valid symbol (array_name) identifying the array, and a subscript value (numeric_expression) identifying the array element. Arrays are global to the compilation unit (i.e. file) in which they occur. You cannot pass an entire array to a form as an argument. However, you can pass the individual elements of an array to a form as read-only arguments. Arrays are one dimensional only and are dynamic in nature. An array extends to the largest element it references, limited only by the amount of virtual memory that is available. Note that array elements are not valid for use with the /TARGET block qualifier. For details regarding the /TARGET qualifier, refer to its description in this manuals Blocks And Block Qualifiers chapter.

Examples:
#BALANCE(1) #TOTAL(#CURRENT_PERIOD)

7-8

Expressions IAF 8.0 DML

Data Elements

Operators
Hierarchy
IAF evaluates operators according to a specific hierarchical precedence. However, you can override this precedence by enclosing a given portion of the operation in parentheses. The following table lists operators in their hierarchical order, highest precedence to lowest precedence, and indicates the class to which each operator belongs. Operator -, NOT, NOT_B ^^ *, / +, & =, <>, >, <, <=, >= AND_B OR_B AND OR Unary Arithmetic Arithmetic Arithmetic String Relational Bitwise Bitwise Logical Logical Class

Operators that this table lists at the same level have equal precedence, and IAF evaluates them as they appear left to right in the comparison expression. The following sections discuss the various classes of operators that IAF provides.

Expressions IAF 8.0 DML

7-9

Data Elements

Arithmetic Operators
The following table lists and describes the arithmetic operators that IAF provides. Operator & + * / ^ Description String addition (concatenation) Numeric addition Subtraction/Unary minus (negation) Multiplication Division Exponentiation

IAF performs any datatype changes that are necessary as a result of using these operators. When converting a string to a numeric value, IAF reads the string from left to right, stopping when it finds a non-numeric character. The examples in the following table illustrate this behavior. If: #A=123A and #B=0 #A=A123 and #B=0 #A=4 and #B=8 #A=APPLE and #B=PEAR (#A + #B) is 123. (#A + #B) is 0. (#A + #B) is 12, while the value of (#A & #B) is 48. (#A + #B) is 0, while the value of (#A & #B) is APPLEPEAR. the value of:

Note that when performing numeric operations, IAF uses a floating point datatype internally. Therefore, the precision of numeric operations within IAF is limited to 15 digits. Attempting to perform numeric operations on values requiring greater precision than 15 digits produces undefined results.

7-10

Expressions IAF 8.0 DML

Data Elements

Logical Operators
IAF provides the following logical operators:
NOT AND OR

These logical operators expect TRUE/FALSE expressions as their operands. Each logical operator performs a particular logical operation on its operands to produce a result of either TRUE or FALSE. An operand is TRUE under any of the following circumstances: The operand is numeric and has a non-zero value. The IAF message files have not been converted from English (the default) to another language, and the operand is a string beginning with Y, y, T, or t. The IAF message files have been converted to another language, and the operand is a string beginning with the first character of the conversions equivalent of Yes or True. An operand is FALSE if it has any other value. For details on converting IAF message files from one language to another, refer to the IAF guide that applies to your operating system. The following table illustrates the effects of the logical operators. A FALSE FALSE TRUE TRUE B FALSE TRUE FALSE TRUE NOT A TRUE TRUE FALSE FALSE A AND B FALSE FALSE FALSE TRUE A OR B FALSE TRUE TRUE TRUE

Bitwise Operators
IAF provides the following bitwise operators:
NOT_B AND_B OR_B

Expressions IAF 8.0 DML

7-11

IAF executes these operators in the same way as the logical operators, but on a bitwise basis. The following table lists the results of some example bitwise operations. Expression (128 AND_B 255) (8 AND_B 16) (64 OR_B -1) (2 OR_B 4) (NOT_B -1) (NOT_B 0) (NOT_B 16) Result 128 0 -1 6 0 -1 -17

Relational Operators
The following table lists and describes the relational operators that IAF provides. Operat or = <> < > <= >= Description Determines if the operand on its left is equal to the operand on its right. Determines if the operand on its left is unequal to the operand on its right. Determines if the operand on its left is less than the operand on its right. Determines if the operand on its left is greater than the operand on its right. Determines if the operand on its left is less than or equal to the operand on its right. Determines if the operand on its left is greater than or equal to the operand on its right.

A relational operation that evaluates to TRUE returns a non-zero value. A relational operation that evaluates to FALSE returns a value of zero. For

7-12

Expressions IAF 8.0 DML

Data Elements

example, the result of the following relational operation is non-zero (TRUE):

DEF > ABC

The result of the following relational operation is zero (FALSE):

100 = 95

Internal Datatype Assignments

When examining an expression that has an operator, IAF assigns each data element an internal datatype of either string, 32-bit integer, or double float as the following examples illustrate: Element 0 0.0 123345 -99.12 0 0.00 Internal Datatype 32-bit integer double float 32-bit integer double float string string

If a data element in an expression that has an operator is a table field, IAF assigns the data an internal datatype based upon the fields native datatype as follows: Fields Native Datatype BYTE, UBYTE, WORD, UWORD, LONGWORD, ULONGWORD BYTE, UBYTE, WORD, UWORD, LONGWORD, ULONGWORD D_FLOAT, F_FLOAT, G_FLOAT, H_FLOAT, NUMTEXT QUADWORD, II_MONEY, NR, NRO, NZ, NU, NL, NLO, PACKED Scale No Yes n/a n/a Internal Datatype 32-bit integer double float double float

Expressions IAF 8.0 DML

7-13

Fields Native Datatype TEXT, DATE_TIME, II_C, II_T, YYMMDD, YYYYMMDD VARYING_STRING, DOCUMENTARY

Scale n/a n/a

Internal Datatype string

Not all native datatypes in the preceding table apply to all database engines. For details on native datatypes that apply to a particular database engine, refer to the IAF guide that applies to that database engine. The following table lists the rules that IAF uses to determine a common datatype for the data elements in a given expression, based upon the type of operator that the given expression uses. Operator Type Numeric (+, -, /, *, ^, unary -) Rule If both data elements are 32-bit integers, IAF leaves them as 32-bit integers. Otherwise, IAF converts both data elements to double float. IAF does not convert the data elements, but evaluates each of them as either TRUE or FALSE (see this chapters Logical Operators section for details). If either data element has a double float internal datatype, IAF converts the other data element to double float. Otherwise, if either data element is a 32-bit integer, IAF converts the other data element to a 32-bit integer. Otherwise, IAF converts both data elements to a string datatype. IAF converts both data elements to 32-bit integers. IAF converts both data elements to string datatypes.

Boolean (AND, OR, NOT)

Relational (=, <>, >, <, <=, >=)

Bitwise (AND_B, OR_B, NOT_B) String (&)

7-14

Expressions IAF 8.0 DML

Chapter 8

Special Variables and Value Symbols

Special Variables

Special variables are variables to which IAF assigns values. These variables contain information pertaining to the operating system and the IAF environment. DML expressions can include special variables. Value symbols are named values that IAF typically assigns to the %STATUS variable to indicate the result of executing a given DML statement. This chapter describes the special variables and value symbols that IAF provides.

Special Variables
%ACCOUNT
When running IAF on OpenVMS, this variable indicates the end users account name. When running IAF on an operating system other than OpenVMS, this variables value is the same as the value of the %USERNAME special variable. For details regarding %USERNAME, refer to its description in this section.

%ACTUAL_BREAK
This variable indicates the break level that caused the current break to trigger. The value of the variable is zero if the break that caused the current break to trigger is a BREAK0 level break. Otherwise, the value is equal to the break level (i.e. 1 for break 1, 2 for break 2, etc.) that triggered the current level break. Note that this variable contains a value only while IAF is executing a level break. Otherwise, this variables value is undefined. For details regarding level breaks, refer to the descriptions of the /BREAK and /BREAK0 qualifiers in this manuals Forms And Form Qualifiers chapter.

%ADD
This variable indicates that the end user pressed the GM_INSERT_ROW key from within a TABLE_EDIT or QUERY form. For details regarding TABLE_EDIT and QUERY forms, refer to this manuals Forms And Form Qualifiers chapter.

8-2

Special Variables and Value Symbols IAF 8.0 DML

Special Variables

%ADVANCED_USER
This variable contains a boolean value indicating whether the Thin Client user as an advanced user. This variable's value is one if the user is an advanced user and zero if the user is not an advanced user.

%ARCHIVE
This variable indicates that the end user appended the /ARCHIVE qualifier to a given DELETE FROM statement. For details regarding the DELETE FROM statement and its qualifiers, refer to this manuals Language Statements chapter.

%BITMAP
This variable contains a boolean value indicating whether menus can use the /BITMAP qualifier to display bitmaps. This vaiable's value is one if bitmaps can be displayed and zero if bitmaps cannot be displayed.

%BROADCAST
This variable contains the user's current broadcast mask as set with the SET BROADCAST statement. The broadcast mask is only applicable to thin client and character cell users on the OpenVMS platform.

%CAT_FILTER
This variable stores the value of a table name that is currently on the virtual table GEM_CAT_RELATION_FIELDS_FILTER. The virutal table GEM_CAT_RELATION_FIELDS_FILTER is associated with this special variable. Whenever the value of this special variable is changed by setting another table name, the virtual table mentioned will contain all columns associated with the table name contained in %CAT_FILTER.

%CURRENT_BREAK
This variable indicates the level of the currently executing level break. Note that this variable contains a value only while IAF is executing a level break. Otherwise, this variables value is undefined. For details regarding level breaks, refer to the descriptions of the /BREAK and / BREAK0 qualifiers in this manuals Forms And Form Qualifierschapter.

Special Variables and Value Symbols IAF 8.0 DML

8-3

Special Variables

%DATABASE
This variable indicates the name of the current default database. For details on how IAF determines the current default database, refer to the descriptions of the SET DATABASE and INVOKE statements in this manuals Language Statements chapter.

%DEFAULT_ENGINE
This variable contains the name of the default database engine.

%DELETE
This variable indicates that the end user pressed the GM_DELETE_ROW key from within a TABLE_EDIT or QUERY form. For details regarding TABLE_EDIT and QUERY forms, refer to this manuals Forms And Form Qualifiers chapter.

%E
This variable contains the approximate value of the constant E. = 2.7182818284590...

8-4

Special Variables and Value Symbols IAF 8.0 DML

Special Variables

%EDIT_MODE
This variable indicates the current edit mode of a TABLE_EDIT or QUERY form. The %EDIT_MODE variables value can be %ADD, %DELETE, %DISPLAY (QUERY forms only), %MODIFY, %FIND, or zero (for forms in which edit mode does not apply). The following example tests %EDIT_MODE in an IF constructs condition expression:
BEGIN_BLOCK ADD_NEW_FLAG IF (%EDIT_MODE=%ADD) INPUT_BLOCK FLAG /COL=2 /ROW=2 /TARGET=CUSTOMERS(FLAG) END_IF END_BLOCK

For details regarding TABLE_EDIT and QUERY forms, refer to this manuals Forms And Form Qualifierschapter. Note: Comparing against %DELETE in a QUERY form will not give you your desired results since control is not returned back to the DML code when the delete key is pressed. What you should do is define an alternate form, and within that form, compare %EDIT_MODE against %DELETE. You could also define a delete form for the QUERY form.

%ENTRY_MENU
This variable contains the name of the entry menu as set with the SET ENTRY_MENU statement.

%EXIT_FORM_ACTIVE
This special variable contains 1 when an exit handler form is executing and 0 otherwise.

%EXIT_FORM_ENABLED
This special variable contains 1 if either the global exit handler form is enabled or if a local exit handler form for the currently executing form is enabled; contains 0 otherwise.

%EXIT_FORM_FILENAME
This special variable contains the form filename associated with the currently enabled local exit handler form for the currently executing form. If no local exit handler form is enabled, but a global exit handler form is

Special Variables and Value Symbols IAF 8.0 DML

8-5

Special Variables

enabled, then it contains the form filename associated with the global exit handler form. It is blank if neither local nor global exit handler forms are enabled.

%EXIT_FORM_FORMNAME
This special variable contains the form file entry point form name associated with the currently enabled local exit handler form for the currently executing form. If no local exit handler form is enabled, but a global exit handler form is enabled, then it contains the form file entry point form name associated with the global exit handler form. It is blank if neither local nor global forms are enabled.

%EXIT_FORWARD
This variable indicates that the end user pressed the GM_EXIT_FORWARD key to exit the given form. Note that you can use the command EXIT(%EXIT_FORWARD) to force an exit forward condition to take place in a form. For details regarding the EXIT statement, refer to this manuals Language Statements chapter.

%FACILITY
Upon execution of a facility via any means (MENU statement, PERFORM /FACILITY statement, stored procedure execution, etc) the %FACILITY special variable is set to the name of the currently executing facility. The %FACILITY special variable is cleared when the facility finishes executing. The format of the facility name contained in the %FACILITY special variable is as follows: database-handle.systemname:facility-name.

%FACILITY_DATABASE
Same as %FACILITY above except that this special variable contains only the database-handle portion of the full facility name.

8-6

Special Variables and Value Symbols IAF 8.0 DML

Special Variables

%FACILITY_NAME
Same as %FACILITY above except that this special variable contains only the facility-name portion of the full facility name.

%FACILITY_SYSTEM
Same as %FACILITY above except that this special variable contains only the system-name portion of the full facility name.

%FIND
This variable indicates that the end user pressed the GM_FIND_ROW key from within a TABLE_EDIT or QUERY form. For details regarding TABLE_EDIT and QUERY forms, refer to this manuals Forms And Form Qualifierschapter.

%FORM_FILE
This variable indicates the full file specification of the DML source file (filetype .dml) that IAF is currently executing.

%FORM_NAME
This variable indicates the name of the form that IAF is currently executing. For details regarding forms, refer to this manuals Forms And Form Qualifiers chapter.

%GEM_INIT
This variable contains the name of the DML initialization file as set with the GEM_INIT SCV.

%GTID
The %GTID special variable contains the IAF transaction identifier while a transaction is active. The value changes each time the transaction level, as indicated by the %TRANS_LEVEL special variable, transitions from zero to one and from one to zero. It does not change as the transaction level increases beyond one (pseudo transactions). %GTID has a null value () when no transaction is active. For more information, see Appendix G, IAF Transaction Identifiers.
Special Variables and Value Symbols IAF 8.0 DML 8-7

Special Variables

%GTID_LEVEL
This variable contains the current global transaction identifier level that is incremented and decremented with the START_GTID and END_GTID statements.

%HARDWARE
This variable returns a string indicating the type of hardware on which IAF is currently running. Valid values for this variable are as follows:
VAX ALPHA HP MIPS INTEL

%HELP_LIBRARY
This variable contains the name of the current help library as set with the GEM_HELP_LIBRARY SCV.

%HOSTID
This variable contains a space separated list of HOSTIDs for the machine on which IAF is running. These are used by IAF licensing.

%INPUT_BACKGROUND
This variable contains the value of the current input background setting as set with the SET INPUT BACKGROUND statement.

%INPUT_DATE_FORMAT
This variable contains the value of the current alternate date input format as set with the SET DATE_FORMAT statement.

%INPUT_FOREGROUND
This variable contains the value of the current input foreground setting as set with the SET INPUT FOREGROUND statement.

8-8

Special Variables and Value Symbols IAF 8.0 DML

Special Variables

%INPUT_PROMPT
This variable contains the value of the current DML prompt setting as set with the SET PROMPT statement.

%INPUT_TIMEOUT
This variable contains the value of the current input timeout setting as set with the SET TIMEOUT statement.

%INPUT_UPDATE
This variable contains the value of the current screen display options settings as set with the SET SCREEN command.

%INTERRUPT
This variable indicates the current interrupt level. The GM_INTERRUPT key facilitates interrupting the current IAF session and beginning a new session (to a maximum of ten sessions). This variables value is zero if the current session is the original IAF session, one if the current session is the first interrupt session, two if it is the second session, and so on. For details regarding the interrupt facility, refer to the IAF Conventions Guide.

%INTERRUPT_COMMAND
This variable contains the interrupt command string as set by the SET INTERRUPT statement.

%IS_ADMIN
This variable returns TRUE when the current user is identified as an administrator by IAF.

%KEYBOARD_FILE
This variable contains the name of the keyboard key mapping file as set with the SET KEYBOARD statement.

Special Variables and Value Symbols IAF 8.0 DML

8-9

Special Variables

%LANGUAGE
This variable indicates, in English, the current language (for example; SPANISH, FRENCH, and so on.) defined via the SYS$LANGUAGE or GEM_LANGUAGE System Customization Variable (as appropriate for the given operating system). To determine which of these language SCVs is applicable to a particular operating system, refer to the IAF guide that applies to that operating system. If the appropriate SCV is undefined, this variables value is ENGLISH.

%LOCK_OPTIONS
This variable contains the current lock options as set with the SET LOCK statement.

%LOG_FILE
This read-only Special Variable returns the file specification of the log file.

%LOGGING_DEBUG
This read-only Special Variable returns TRUE if the current logging level is less than or equal to "DEBUG".

%LOGGING_ERROR
This read-only Special Variable returns TRUE if the current logging level is less than or equal to "ERROR".

%LOGGING_INFO
This read-only Special Variable returns TRUE if the current logging level is less than or equal to "INFO".

%LOGGING_WARNING
This read-only Special Variable returns TRUE if the current logging level is less than or equal to "WARNING".

8-10

Special Variables and Value Symbols IAF 8.0 DML

Special Variables

%MASK_CURRENCY_SIGN
This variable contains the currency sign character used when masking currency values.

%MASK_DIGIT_SEPARATOR
This variable contains the digit separator character used when masking numeric values.

%MASK_RADIX_POINT
This variable contains the radix point character used when masking numeric values.

%MODE
This variable indicates the mode in which IAF is currently running. This variables value can be INTERACTIVE, BATCH, or NETWORK.

%MODIFY
This variable indicates that the end user pressed the GM_SELECT_ROW key from within a TABLE_EDIT or QUERY form. For details regarding TABLE_EDIT and QUERY forms, refer to this manuals Forms And Form Qualifierschapter.

%NODENAME
This variable contains the machine nodename or hostname.

%NOW
This variable indicates the current date and time in the format, DD-MonYYYY HH:MM:SS.CC.

%OPERATING_SYSTEM
This variable returns a string indicating the name of the operating system under which IAF is currently running. Valid values for this variable are as follows:

Special Variables and Value Symbols IAF 8.0 DML

8-11

AIX HP-UX MS-DOS OpenVMS OSF/1 ULTRIX Windows NT Windows 95 Windows 98

For details on using IAF on a particular operating system, refer to the IAF guide that applies to that operating system.

%PAGE
This variable indicates the current page number of the current report and is applicable only to REPORT forms. For details regarding REPORT forms, refer to this manuals Forms And Form Qualifierschapter.

%PERFORM
This variable contains the current file type search order setting used by the PERFORM statement and as set with the SET PERFORM statement.

%PI
This variable contains the approximage value of the constant PI = 3.14159...

%PID
This variable indicates the current processs full process ID.

%PLATFORM
This variable contains the operating system platform that is used by IAF licensing.

8-12

Special Variables and Value Symbols IAF 8.0 DML

Special Variables

%PRECISION
This variable contains the numeric comparison "fudge factor" setting used by the DML interpreter when comparing floating point numeric values. Floating point numeric values that differ by no more than this amount are considered to be equal in value. Set with the SET PRECISION statement.

%PRINT_MODE
This variable contains the thin client print mode, CLIENT or SERVER.

%QUERY_CUR_REC
This variable indicates the number of the current record, relative to the number of records selected via the last FIND query in the current QUERY form. For details regarding QUERY forms, refer to this manuals Forms And Form Qualifierschapter.

%QUERY_MAX_REC
This variable indicates the number of records selected via the last FIND query in the current QUERY form. For details regarding QUERY forms, refer to this manuals Forms And Form Qualifierschapter.

%QUERY_MODE
This variable contains a description of the current QUERY forms query mode. Do not use this variable to test for the current edit mode because the description that this variable contains may vary from language to language. To test for the current edit mode, use the %EDIT_MODE special variable. For details regarding %EDIT_MODE, refer to its description in this chapter. For details regarding QUERY forms, refer to this manuals Forms And Form Qualifiers chapter.

%REPORT_DATE
This variable indicates the date and time that the current REPORT form began executing. For details regarding REPORT forms, refer to this manuals Forms And Form Qualifiers chapter.

Special Variables and Value Symbols IAF 8.0 DML

8-13

%REPORT_FORM_FEEDS
This variable contains the ON/OFF setting of the GEM_FORM_FEED SCV.

%REPORT_PAGE_SIZE
This variable contains the number of lines per page that will be used for report forms.

%REPORT_MODE
This variable contains the thin client report mode, "CLIENT" or "SERVER".

%REPORT_NAME
This variable indicates the name of the REPORT form that IAF is currently executing. The difference between this variable and the %FORM_NAME variable is that if a REPORT form calls a PROCEDURE form, testing %REPORT_NAME in the PROCEDURE form returns the REPORT forms name, while testing %FORM_NAME in the PROCEDURE form returns the PROCEDURE forms name. For details regarding %FORM_NAME, refer to its description in this chapter. For details regarding REPORT and PROCEDURE forms, refer to this manuals Forms And Form Qualifierschapter.

%ROW_NUMBER
This variable indicates the number of the record that IAF is currently processing in a REPORT or TABLE_EDIT form, or in a NORMAL or PROCEDURE form whose form header statement includes one or more record selection qualifiers. This variables value is one if IAF is processing the first record, two if IAF is processing the second record, and so on. Note that IAF re-numbers the rows in a TABLE_EDIT form after adding or deleting a record from the table edit display, and this may result in an unexpected %ROW_NUMBER value. Therefore, exercise caution when testing this variable in a TABLE_EDIT form.

8-14

Special Variables and Value Symbols IAF 8.0 DML

Special Variables

%SCREEN_MODE
This variable contains the current display BORDER/NOBORDER screen mode setting as set with the SET SCREEN statement.

%SCREEN_WIDTH
This variables value is an integer indicating the current screen display width and is typically 80 or 132. This variable is especially useful when positioning a list of values (LOV) window using the /LOV_WIDTH block qualifier. For details on /LOV_WIDTH and other block qualifiers, refer to this manuals Blocks and Qualifiers chapter.

%SERVER
This variable contains a boolean value indicating that the form is being run as a stored procedure within the environment of a FAT server process. A value of one indicates that the form is running form within a fat server and a value of zero indicates that it is not.

%SHADOW_LEVEL
This variable contains current shadow forms setting as set with the SET SHADOWS statement.

%SIGNATURE_ID
This variable contains the current electronic signature identifier as generated by the last SIGNATURE statement or SIGNATURE_BLOCK.

%STATUS
General
This variable indicates the return status of the last DML statement that IAF executed. However, upon entry to a DML form, the value of this special variable is always %NORMAL. You can use the ERROR_TEXT built-in function to obtain the text associated with a given error value in the %STATUS variable. Typically, this variables value is a value symbol. For details regarding value symbols, refer to this chapters Value Symbols section. For details regarding the ERROR_TEXT built-in function, refer to this manuals BUILT-IN FUNCTIONS chapter.

Special Variables and Value Symbols IAF 8.0 DML

8-15

Special Variables

You can use the BEGIN_SIGNAL_TO_STATUS statement to cause IAF to begin trapping signaled errors to the %STATUS variable. Signaled errors are errors that IAF considers to be fatal to a DML program. By default, signaled errors do not affect %STATUS. For details regarding the BEGIN_SIGNAL_TO_STATUS statement, refer to this manuals Language Statements chapter.

COM Status
The three COM statements set special variable %STATUS upon return. Refer to the "Special Variables and Value Symbols" chapter of the IAF DML manual. The status of the COM operation is accessible within the DML code and provides information for program control. The type of information available is based on Visual Basic's Err object, ActiveX Automation's EXCEPINFO structure and HRESULT, and COM's IerrorInfo interface. The following are valid COM Status statements:

! System supplied return status code #LONG = COCALL object_handle.COSTATUS_S_HRESULT ! User supplied error code #LONG = COCALL object_handle.COSTATUS_E_CODE ! Description of error #LONG = COCALL object_handle.COSTATUS_E_DESCRIPTION ! Full pathname of the Help File #LONG = COCALL object_handle.COSTATUS_E_HELPFILE ! Help context inside Help File #LONG = COCALL object_handle.COSTATUS_E_HELPCONTEXT

! Friendly name of error source #LONG = COCALL object_handle.COSTATUS_E_SOURCE ! Unique COM Identifier of the Object #LONG = COCALL object_handle.COSTATUS_E_GUID

Example 1
FORM EXAMPLE_17 /ROW=1 /COL=1 /WIDTH=8 /HEIGHT=25

! Execute a COCALL statement with few arguments. ! This example tries to invoke a COPY method with less arguments than

8-16

Special Variables and Value Symbols IAF 8.0 DML

Special Variables

! expected.

COCREATE "MyLib.dll" AS MYLIB

#SRC = "D:\TEST.DOC"

! Invoke COPY method which is expecting source and destination files. COCALL MYLIB.COPY(#SRC)

! Get error description. #STRING = COCALL MYLIB.COSTATUS_E_DESCRIPTION

! Print #string and you should see error: ! "Value is /Provided Arguments not equal to Required Argument Count/" print #STRING

! Get error code. Should be 0 for failure. #STRING = COCALL MYLIB.COSTATUS_E_CODE print #STRING

! Test for SUCCESS and take actions accordingly. IF (COCALL MYLIB.COSTATUS_E_CODE = 1)

!Process DML statements here.

END IF CORELEASE MYLIB

END_FORM

%STATUS_FREQUENCY
This variable contains the current status update frequency (in integer seconds) as set with the SET STATUS_FREQUENCY statement.

Special Variables and Value Symbols IAF 8.0 DML

8-17

Special Variables

%SYSTEM
This variable indicates the name of the current default system. You can set the default system via the SET SYSTEM statement. For details regarding systems, refer to the discussion of the System Definition Editor in the IAF System Reference Manual. For details regarding the SET SYSTEM statement, refer to this manuals Language Statements chapter.

%TARGETID
This variable contains the machine target ID that is used by IAF licensing (obsolete).

%TEMPORARY_DIRECTORY
This variable contains the name of the directory in which all temporary files should be created.

%TERMINAL
This variable indicates the name of the current terminal (for example; TXA5:).

%TEXTFILE_MODE
This varible contains the thin server text file mode, "CLIENT" or "SERVER". "CLIENT" indicates that whenever a text file that was open for write is closed with the CLOSE_TEXT, it is copied to the client. "SERVER" indicates that the file is not copied to the client.

%THIN_CLIENT
This variable contains a boolean value that indicates the DML form is running from within the context of a thin client. This is currently impossible. DML code cannot currently run from within the context of a thin client. It always runs from within the context of a thin server (see %THIN_SERVER on page 8-20). Therefore, this variable is currently always zero.

8-18

Special Variables and Value Symbols IAF 8.0 DML

Special Variables

%THIN_CLIENT_CHARSET
This variable contains the GEM_CHARACTER_SET SCV setting as set on the thin client machine. When the values of %THIN_CLIENT_CHARSET and %THIN_SERVER_CHARSET differ, IAF performs character set conversion in both directions.

%THIN_CLIENT_HW
This variable is the same as the %HARDWARE variable, but for the thin client machine.

%THIN_CLIENT_IPCNAME
This variable contains the IPCNAME of the thin client.

Special Variables and Value Symbols IAF 8.0 DML

8-19

Special Variables

%THIN_CLIENT_MODE
This variable contains the operating mode of the thin client. Possible values are CHARACTER CELL, X-WINDOWS GUI, SIMPLIFIED, MS-WINDOWS GUI, UNKNOWN, IBROWSER GUI and SIMPLIFIED IO.

%THIN_CLIENT_OS
This variable is the same as the %OPERATING_SYSTEM variable, but for the thin client operating system.

%THIN_CLIENT_REPORT_DIR
This variable contains the directory into which report files will be placed on the thin client.

%THIN_CLIENT_TYPE
This variable contains the thin client type. Possible values are GTC, GTX, PORTAL, GCWPRO, IBROWSER GUI, X-WINDOWS GUI, SIMPLIFIED IO and CHARACTER CELL.

%THIN_CLIENT_USERNAME
This variable contains the username of the thin client user. That is, the name of the account into which the user who is running the thin client executable is currently logged in to on the thin client machine. This can be very different from the name of the account into which the user is logged into on the thin server machine.

%THIN_SERVER
This variable contains a boolean value that indicates the DML form is running from within the context of a thin server. A value of one indicates a thin server. A value of zero indicates not a thin server.

8-20

Special Variables and Value Symbols IAF 8.0 DML

Special Variables

%THIN_SERVER_CHARSET
This variable contains the GEM_CHARACTER_SET SCV setting as set on the thin server machine. When the values of %THIN_CLIENT_CHARSET and %THIN_SERVER_CHARSET differ, IAF performs character set conversion in both directions.

%THIN_SERVER_DBCHARSET
This variable contains the GEM_DB_CHARSET SCV setting as set on the thin server machine.

%THIN_SERVER_HW
This variable is the same as the %HARDWARE variable, but for the thin server machine.

%THIN_SERVER_IPCNAME
This variable contains the IPCNAME of the thin server.

%THIN_SERVER_MODE
This variable contains the operating mode of the thin server. Possible values are CHARACTER CELL, X-WINDOWS GUI, SIMPLIFIED, MS-WINDOWS GUI, UNKNOWN, IBROWSER GUI and SIMPLIFIED IO.

%THIN_SERVER_OS
This variable is the same as the %OPERATING_SYSTEM variable, but for the thin server operating system.

%THIN_SERVER_REPORT_DIR
This variable contains the directory into which report files will be placed on the thin server.

Special Variables and Value Symbols IAF 8.0 DML

8-21

Special Variables

%THIN_SERVER_USERNAME
This variable contains the username of the thin server user. That is, the name of the account into which the user is logged into on the thin server machine.

%TITLE_FORM
This variable contains the file specification of the title form as set with the SET TITLE_FORM statement.

%TODAY
This variable indicates todays date in the format DD-Mon-YYYY, with an implicit time of 00:00:00.00.

%TRANS_LEVEL
This variable indicates the number of transactions that are currently outstanding. A zero value indicates that there are no outstanding transactions. A non-zero value indicates the number of outstanding transactions in progress. This variable is intended primarily for use when debugging programs that run in multiple-user environments. For information regarding transactions and multiple-user environments, refer to the IAF Users Guide. For details regarding statements that can modify this variable, refer to the descriptions of the START_TRANSACTION, COMMIT, and ROLLBACK statements in this manuals Language Statements chapter.

%UIC
This variable indicates the current combination of group and user ID.

%UIC_GRP
This variable indicates the current users group number.

%UIC_MEM
This variable indicates the current users member number.

8-22

Special Variables and Value Symbols IAF 8.0 DML

Special Variables

%UNIX
This variable contains a Boolean value indicating whether IAF is currently running on a UNIX- based operating system. This variables value is zero if IAF is not currently running on a UNIX- based operating system, or non-zero if IAF is currently running on a UNIX-based operating system. For details on using IAF on a particular operating system, refer to the IAF guide that applies to that operating system.

%USERNAME
This variable indicates the current users username.

%VERSION
This variable indicates the number of the IAF version that is currently running. The format of the version number is as follows:
n.m-xxx

where n is a one or two digit major version number, m is a one or two digit minor version number, and xxx is a literal of undefined format used to signify edit levels, field test versions, or other version information.

%WD
This variable contains the value of the user's current working directory (aka default directory).

%XPID
This variable contains the value of the process identifier in hexadecimal rather than decimal format.

Special Variables and Value Symbols IAF 8.0 DML

8-23

Value Symbols

Value Symbols
Value symbols are return values that IAF typically assigns to the %STATUS special variable upon executing a given DML statement. You cannot assign values to value symbols. The following table lists the available value symbols, and for each value symbol, indicates a typical condition under which IAF would use the given value symbol as a return status. Value Symbol %ASSERT_FAILURE Condition Execution of an ASSERT statement failed. This symbol can be used to check for failure of test procedures when writing unit tests. The end user presses the GM_BACK key at the first input in a form. Row data is being returned. A PERFORM specifying the / NODEADLOCK_EXIT qualifier results in a deadlock condition. No records are found in a read-only TABLE_EDIT form or a QUERY form. The end user presses the GM_EXIT key at an input. A given statements execution is not successful. A given statements execution takes place normally. A given statements execution is successful.

%BACK %DATA %DEADLOCK

%EMPTY %EXIT %FAILURE %NORMAL %SUCCESS

For details on the value symbol(s) that a particular DML statement returns, and the condition(s) under which the statement returns the value symbol(s), refer to the description of that DML statement in this manuals Language Statements chapter.

8-24

Special Variables and Value Symbols IAF 8.0 DML

Security Symbols

Security Symbols
IAF provides table security value symbols to facilitate testing for the access rights that the current user has for a particular table, and are intended for use with the TABLE_SECURITY built-in function as the following example illustrates:
IF (TABLE_SECURITY(EMPLOYEES) AND_B %MODIFY_ACCESS) PERFORM MODIFY_EMPLOYEE_DATA ELSE ERROR Insufficient access rights. END_IF

The following table lists the available security symbols, and for each one, indicates the access right it represents. Security Symbol %ADMIN_ACCESS %CHANGE_ACCESS %CONTROL_ACCESS %DEFINE_ACCESS %DELETE_ACCESS %ERASE_ACCESS %MODIFY_ACCESS %OPERATOR_ACCESS %READ_ACCESS %SHOW_ACCESS %WRITE_ACCESS Access Right User has administrative access to data. User may modify metadata. User may change security for the given table. User may define new metadata. User may delete the given table. User may delete records. User may update current records. User has operator rights. User has read access to data. User may read the given tables metadata (always true). User may add new records.

For details regarding the TABLE_SECURITY built-in function, refer to this manuals BUILT-IN FUNCTIONS chapter. For more information regarding table security, refer to the IAF guide that applies to your database engine.

Special Variables and Value Symbols IAF 8.0 DML

8-25

Chapter 9

Built-In Functions

The DML includes built-in functions that perform a variety of operations on data and metadata. This chapter describes the DMLs string manipulation, numeric, date and time, data definition, facility, and miscellaneous functions. By default, these functions operate on data and metadata in the default database. However, some functions enable you to optionally specify a database handle. For details on default database designation, refer to the descriptions of the SET DATABASE and INVOKE statements in this manuals Language Statements chapter.

9-2

Built-In Functions IAF 8.0 DML

String Manipulation Functions

String Manipulation Functions

AMONG(value, range-list-1 [, range-list-2 range-list-254) This

function acts similarly to the AMONG record selection operator. It accepts from 2 to 255 parameters. The Boolean result 1 is returned if value is found. The Boolean result 0 is returned if value is not found. Value is the value being checked. This function is polymorphic. Text values, date/time values, delta-time values, and numeric values are all permitted and handled appropriately. Range-list-1 can be a single value, a string containing a dash separated range of values, a comma separated string containing multiple values, a comma separated string containing multiple dash separated ranges of values, or a string containing a mixture of single values and dash separated ranges of values. Values containing dashes should be quoted in order to ensure they are not treated as ranges. Range-list-2 through range-list-254 are optional and have the same specifications as range-list-1.
ASCII (source_character) This function returns the source characters

numeric ASCII value and is useful when packing and unpacking data. The ASCII function converts only the first character of a multiplecharacter string. Following is an example of the ASCII function in use:
#A=ASCII(-)

This example places the value 45 in #A.

BASE64_DECODE(source_string) Converts a BASE-64 encoded

source string to a binary result string.

BASE64_ENCODE(source_string) Converts binary data in the source

string to BASE-64 encoded result string. The result string must not exceed 65,535 bytes.
CHR(numeric_value) This function converts a numeric ASCII value (in

the range 0-255) to its designated character. IAF translates numbers outside the 0-255 range to mod(255), and converts the resulting value to its designated character.
COMPRESS(source_string) This function returns the specified source string as a compressed string (a string in which all spaces and tabs are reduced to single spaces).

Built-In Functions IAF 8.0 DML

9-3

String Manipulation Functions

COMPRESS_ALL(source_string) This function returns the specified source string with all spaces and tabs removed. count = CSV_SPLIT(#array(), csv-text [,options] [,comma] [,quote] [,escape]) This function takes a comma separated variable (CSV) format

text string and breaks it apart into an array of text strings. The function result is the count of the number of text string elements in the resulting array. The resultant text string elements start at element number one and continue through element number count. Options, comma, quote and escape are all optional. Count is the number of text string elements in the resulting array. #array() is the output array that will contain the resulting text strings. Csv-text is the comma separated variable format text string. Options is a comma separated list of keyword options. The available options are: ALWAYS_QUOTE and DOUBLE_QUOTE. Comma is the character to use as the field separator. The field separator character does not have to be a comma character. For instance, semi-colon and colon are often used. By default the field separator is a comma character. A comma character is also used if "" (null string) is specified as the comma character. Quote is the quote character. By default the quote character is an ASCII double quote. An ASCII double quote is also used if "" (null string) is specified as the quote character. Escape is the escape character. There is no default escape character.
CSV_MERGE(#array() [,count] [,options] [,comma] [,quote] [,escape]) This function turns an array of text strings into a comma

separated variable (CSV) format text string. Count, options, comma, quote and escape are all optional. #array() is the input array containing the text strings. Count is the optional number of elements in the array to use as input if not the entire array. Input text string elements in the array start at element number one and continue through element number count. Options is a comma separated list of keyword options. The available options are: ALWAYS_QUOTE and DOUBLE_QUOTE.

9-4

Built-In Functions IAF 8.0 DML

String Manipulation Functions

Comma is the character to use as the field separator character. The field separator character does not have to be a comma character. For instance, semi-colon and colon are often used. By default the field separator is a comma character. A comma character is also used if "" (null string) is specified as the comma character. Quote is the quote character. By default the quote character is an ASCII double quote. An ASCII double quote is also used if "" (null string) is specified as the quote character. Escape is the escape character. There is no default escape character.
DATA_COMPRESS(input-string) This function performs reversible data compression. The input string is compressed with the ZLIB compress function. The compressed text returned is prefixed with a littleendian unsigned 16-bit integer containing the original uncompressed string length. The compressed text including the length prefix is limited to a total of 65,535 bytes, which is the DML text string length limitation. DATA_UNCOMPRESS(input-string) This function uncompresses a string that was compressed with the DATA_COMPRESS function. The little-endian 16-bit integer uncompressed text length is first removed, a new output string equal in length to the original uncompressed text is allocated, and then the remaining input string is uncompressed into the output string. ELEMENT(element-number, source-string [,delimiter-string]) This

function returns an element from a source-string in which the elements are separated by a specified delimiter. The element number is one based. The delimiter-string is optional. The default delimiter is the comma character.
EXPAND(source_string) This function returns the source string in an

exploded state (IAF inserts a space after every character in the source string, including blank characters).
IS_TRUE(input-string) This function implements the IAF DML Runtime Library's standard rules for T[RUE] , F[ALSE] , Y[ES] / N[O] , any-odd-number , any-even-number System Customization Variable settings. The Boolean result 1 is returned If the first character of the input string is "T", "t", "Y", "y" or if the input string contains any odd number. The Boolean result 0 is returned if the first character of the input string is "F", "f", "N", "n", or if the input string contains any even number.

Built-In Functions IAF 8.0 DML

9-5

String Manipulation Functions

LEFT(source_string,end_position) This function returns the left-most

characters of the given source string up to and including the character in the position that the end position specifies.
LEN(source_string) This function returns the length of the specified

source string.
LOWERCASE(source_string) This function returns the given source string with all alphabetic characters converted to lowercase. Following is an example of the LOWERCASE function in use:
#A=LOWERCASE(JOHN)

This examples places the string john in #A.

LPAD(input-string, length [,pad-character]) This function returns a copy of the input-string padded to the specified length with the specified pad character. Padding characters are added to the leading end (left side) of the string. The default pad character is an ASCII space. The optional pad-character string may be specified to cause the string to be padded with a character you specify. Note that only the first character of the padcharacter string is used. LTRIM(input-string) This function returns a copy of the input string with all leading tab and space characters removed. LTRIM(source_string) This function returns the given source string with

any leading spaces and tabs removed.MID(source_string,start_position,length) This function returns a substring of the given length from the specified source string. IAF extracts the substring beginning with (and including) the character that the start position specifies. Following is an example of the MID function in use:
#X=IAF MID(#X,2,3)

This example places the string EMB in #A.

MATCHING(candidate-string, pattern-string) This function compares a

candidate string with a pattern string that in addition to any other normal characters may also include the "*" and "%" wildcard pattern matching characters. The Boolean value 1 is returned if the candidate string matches the pattern string. The Boolean value 0 is returned in the candidate string does not match the pattern string.

9-6

Built-In Functions IAF 8.0 DML

String Manipulation Functions

MERGE(#array() [,count]) This function takes an array, recombines

each element starting at element number one up to the optional count (or the whole array if no count is specified) and returns a string containing a comma separated list of items. #array() is the array of elements to merge. Count is the optional number of elements in the array to use as input if not the entire array. Input elements in the array start at element number one and continue through element number count.
POS(source_string,substring,start_position) This function returns

the specified substrings position within the specified source string. IAF searches for the substring starting from the position that the start position specifies. The value that this function returns is relative to the source strings first character. This function returns a zero value if IAF does not find the substring. Note that IAF always returns a value of one if you specify a null substring (). The following table contains examples of the POS function in use. Example POS(ABCDEF,CD,1) POS(IAF,BAS,3) POS(ABC,,1) 3 4 1 Result

QUOTE(input-string) This function quotes text in a style that is acceptable as input to the DML compiler and interpreter. That is, it first tries to quote using double quotes, then tries single quotes and finally tries the character octal 337. RANGE_MERGE(#from_array(), #to_array() [,count]) This function returns a multiple input block style comma separated AMONG range list from a pair of arrays.

#from_array() is the array of range from elements. #to_array() is the array of range to elements. Count is the optional number of elements in each of the arrays to use as input if not the entire arrays. Input elements in each of the arrays start at element number one and continue through element number count.

Built-In Functions IAF 8.0 DML

9-7

String Manipulation Functions

If a range has only a from portion and no to portion (i.e. is not a range), then specify the from element in the from array and a null string as the corresponding to element in the to array.
count = RANGE_SPLIT(#from_array(), #to_array(), among-text [,type]) This function takes a multiple input block style AMONG range

list and breaks it apart into a pair of arrays. Count is the number of text string elements in each of the resulting arrays. #from_array() is the resulting array of range from elements. #to_array() is the resulting array of range to elements. Among-text is the multiple input block style comma separated range list to use as input. Type should be specified as "DATE" if the items are ADT style (dd-monyyy) formatted dates; "" (null string) or omitted entirely otherwise.
REPLACE(source-string, starting-position, ending-position, replacement-string) This function replaces part of a string with another

string. The substring to be replaced is specified by its starting and ending positions. The starting and ending positions are one based numbers of characters starting from the beginning (left side) of the source-string. If the starting-position is less than one, then it is assumed to be one. If the ending-position is less than one, this it is assumed to be one. If the ending-position is beyond the end of the source-string, then the ending-position is assumed to be the length of the source-string.
RIGHT(source_string,start_position) This function returns the rightmost characters of the specified source string beginning with and including the character in the position that the start position specifies. RMD160(input-string) This function returns the 160-bit RIPEMD-160

message digest (cryptographic hash) of the specified input-string. The digest value returned is encoded as a string of 40 hexadecimal ASCII characters. A cryptographic hash is a string one-way hash function that cannot be revered without considerable difficulty.
RPAD(input-string, length [,pad-character]) This function returns a

copy of the input-string padded to the specified length with the specified
9-8 Built-In Functions IAF 8.0 DML

String Manipulation Functions

pad character. Padding characters are added to the trailing end (right side) of the string. The default pad character is an ASCII space. The optional pad-character string may be specified to cause the string to be padded with a character you specify. Note that only the first character of the padcharacter string is used.
RTRIM(input-string) This function returns a copy of the input string with all trailing (right side) ASCII tab and space characters removed. SCRAMBLE(input-string) This function scrambles a string using a

proprietary reversible weak encryption algorithm.

SEG(input-string, starting-position, ending-position) This function

extracts a substring from the input-string and returns the result. The substring begins with the character at the specified starting-position ends with the character at the specified ending-position. The starting-position is the one based number of characters starting from the beginning (left end) of the string. If the starting-position is less than one, then it is assumed to be one. If the starting-position is greater than the ending-position or the length of the input-string, then a null string is returned. If the ending position equals the starting position, then a string consisting of the single character at the starting-position is returned. Unless the ending-position is greater than the length of the input-string, the length of the returned substring equals the ending-position minus the starting-position plus one. If the ending-position is greater than the length of the input-string, then a string consisting of all characters from the starting-position to the end of the input-string is returned.
count = SPLIT(#array(), input-string [,delimiter]) This function takes an input string, splits it on commas (or an optional specified delimiter character and populates the array starting at element number one with the individual items.

Note that this function does not parse delimiters found within quotes. Therefore each item can further contain delimited text in quotes. Count is the number of text string elements in the resulting array. #array() is the output array that will contain the resulting text strings.

Built-In Functions IAF 8.0 DML

9-9

String Manipulation Functions

Input-string is a string containing delimiter separated text. Delimiter is the delimiter to use. The default delimiter is a comma character.
STARTING_WITH(source-string, sub-string) This function returns

Boolean 1 if the source-string starts with the sub-string. It returns Boolean 0 if the source-string does not start with the sub-string.
STRING(duplication_count,ascii_character_value) This function

returns a string consisting of the given ASCII character duplicated the number of times that the duplication count specifies. Following is an example of the STRING function in use:
#A=STRING(10,43)

This example places the string ++++++++++ in #A. You can also use the ASCII function with the STRING function if you do not know a given characters ASCII value. Following is an example that uses the STRING and ASCII functions together:
#A=STRING(10,ASCII(-))

This example places the string ----- in #A.

TRANSLATE(source_string, source_character_set_name, target_character_set_name) Performs character set translation from

the source character set to the target character set. See appendix I for the complete list of character sets supported by IAF for use with the TRANSLATE function. The result string must not exceed 65,535 bytes.
TRIM(source_string) This function returns the given source string with any trailing spaces and tabs removed. UNQUOTE(input-string) This function unquotes text that was quoted

with the QUOTE function. It removes one set of quotes from around the input string (if there are any and they match).
UNSCRAMBLE(input-string) This function unscrambles a string that

was scrambled using the SCRAMBLE function.

UPPERCASE(source_string) This function returns the given source

string with all alphabetic characters converted to uppercase. VALIDATE_DML This function verifies whether a string is a valid DML statement. The string is syntax checked against the compiler to ensure validity.

9-10

Built-In Functions IAF 8.0 DML

Numeric Functions

Examples:
#status = validate_dml("print #b")

If the value of #status is equal to 1 (for True), the string is a valid DML statement.
#status = validate_dml("print asdf")

If the value of #status is not equal to 1, the string is not a valid DML statement.

Numeric Functions
ABS(real_number) This function returns the absolute value of the given

number or numeric expression. Following are examples of the ABS function in use:
ABS(2.3) ABS(-2.3)

These examples return the value 2.3.

ABS(145) ABS(-145)

These examples return the value 145.

ACOS(cosine) Given the cosine of an angle, this function returns the angle (in radians). ACOSD(value) This functions returns the angle (in degrees.) ACOSH(value) This function returns the hyperbolic arg cosing function. ACOT(value) This function returns the arc cotangent function (in

radians.)
ACOTD(value) This function returns the arc cotangent function (in

degress)
ACOTH(value) This function returns the hyperboic arg contangent

function.
ACSC(value) This function returns the arc cosecant function (in

radians.)

Built-In Functions IAF 8.0 DML

9-11

Numeric Functions

ACSCD(value) This function returns the arc cosecant function (in

degrees.)
ACSCH(value) This function returns hyperbolic arg cosecant. ASEC(value) This function returns the arc secant (in radians.) ASECD(value) This function returns the arc secant (in degress.) ASECH(value) This function returns the hyperbolic arg secant. ASIND(value) This function returns the arc sine (in degrees.) ASINH(value) This function returns the hyperbolic arg sine. ATAND(value) This function returns the arc tangent (in degrees.) ATAND2(value) This function returns the angle whose tangent is y/x (in

degrees.)
ATANH(value) This function returns the hyperbolic arg tangent. ASIN(sine) Given the sine of an angle, this function returns the angle (in

radians).
ATAN(tangent) Given the tangent of an angle, this function returns the angle (in radians). ATAN2(sine,cosine) Given a sine and cosine, this function returns the

angle (in radians) whose tangent is the quotient of the sine and cosine.
BINARY_TO_POLY(binary_string,format) This function interprets the

given binary string as raw data of the datatype that the given format specifies. IAF then converts the raw data to a datatype that IAFs polymorphic variables accept.
CEIL(number) This function returns the closest integer that is greater than or equal to the given floating point number. COS(angle) This function returns the cosine of the given angle (in

radians).
COSD(value) This function returns the cosine (in degrees.) COSH(value) This function returns the hyperbolic cosine of the given

value.
COT(value) This function returns the contangent (in radians.)

9-12

Built-In Functions IAF 8.0 DML

Numeric Functions

COTD(value) This function returns the contangent (in degrees.) COTH(value) This function returns the hyperbolic cotangent. CSC(value) This function returns the cosecant (in radians.) CSCD(value) This function returns the cosecant (in degrees.) CSCH(value) Computes the hyperbolic cosecant. DEG(value) Converts radians to degrees. EXP(value) This function returns the base e (expotential) power function

(e^x).
EXP2(value) This function returns the base 2 power function (2^x). EXP10(value) This function returns the base 10 power function (10^x). FAC(value) Computes the factorial. FIX(value) This function returns the integer portion (no rounding.) FRAC(value) This function returns the fractional portion (no rounding.) FLOOR(number) This function returns the closest integer that is less

than or equal to the given floating point number.

GCD(value, value) Computes the Greatest Common Divisor of two

numeric values.
INT(real_number) This function returns an integer that is the given real

number with any fraction removed. The following table contains examples of the INT function in use. Example INT(2.56) INT(-2.58) INT(.58) Result 2 -2 0

LOG2(value) This function returns the base 2 logarithm. LOG(value) This function returns the natural (base e) logarithm of the

given value.

Built-In Functions IAF 8.0 DML

9-13

Numeric Functions

LOG10(value) This function returns the common (base 10) logarithm of

the given value.

MAX(value, value, value,) Returns the maximum value of from 2 to

255 numeric values.

MIN(value, value, value,) Returns the minimum value of from 2 to

255 numeric values.

MOD(dividend,divisor) This function returns the remainder of the

dividend divided by the divisor.

MROUND(x,y) This function returns a number x rounded to the desired

multiple y. MROUND rounds up, away from zero, if the remainder of dividing a number by a multiple is greater than or equal to half the value of the multiple. MROUND returns an error if x or y are zero or if their signs dont match. The syntax for MROUND is as follows. MROUND(num, multiple) The num argument is the number you want to round, and multiple is the value used for the rounding. To round to the nearest 50, then the multiple would be 50. For example: Round 10 to a multiple of 3 = 9 Round 1.3 ot a multiple of 0.2 = 1.4
POLY_TO_BINARY(value,format[,length][,scale]) This function formats the given value based upon the datatype that the given format specifies, and based upon the optional length and scale, if present. This function returns a string that contains the raw binary data. RAD(value) Converts degrees to radians. RANDOM(range) This function returns a random integer value between

zero (inclusive) and the value that the range parameter specifies (exclusive). For example, specifying a range of 2 causes IAF to return either 0 or 1, but never 2.
ROUND(real_number,decimal_place) This function returns a text string rounded to the given number of decimal places. If you need a

9-14

Built-In Functions IAF 8.0 DML

Numeric Functions

numeric rather than a text result; you can either add zero to the result or multiply it by one. IAF rounds up values greater than or equal to .5, and rounds down values less than .5. The following table contains examples of the ROUND function in use. Example ROUND(2.342,2) ROUND(2.349,2) ROUND(2.349,1) ROUND(-2.342,2) ROUND(-2.349,2) 2.34 2.35 2.3 -2.34 -2.35 Result

You can specify a negative number of places to cause IAF to round to an integer value. The examples in the following table illustrate this. Example ROUND(234.2,-2) ROUND(250,-2) ROUND(234.9,-3) 200 300 0 Result

Note that when rounding floating point numbers, the number of decimal places to which you are rounding must be less than the number of places in the precision level that IAF is using in order to produce a meaningful result. For details regarding the precision level that IAF uses, refer to the discussion of the SET PRECISION statement in this manuals Language Statements chapter.
SEC(value) This function returns the secant (in radians.) SECD(value) This function returns the secant (in degrees.) SECH(value) This function returns the hyperbolic secant. SIGN(value) Returns -1 for negative values, 0 for zero, and 1 for positive

values.
SIN(angle) This function returns the sine of the given angle (in radians).

Built-In Functions IAF 8.0 DML

9-15

Numeric Functions

SIND(angle) This function returns the sine of the given angle (in

degrees.)
SINH(angle) This function returns the hyperbolic sine of the given value. SQRT(value) This function returns the square root of the given value. TAN(angle) This function returns the tangent of the given angle (in

radians).
TAND(value) This function returns the tangent (in degrees.) TANH(value) This function returns the hyperbolic tangent of the given

value.

9-16

Built-In Functions IAF 8.0 DML

Date and Time Functions

Date and Time Functions

DATE(days) This function returns the date that occurs the given number

of days after the system base date (17- Nov-1858), in the format DDMon-YYYY. This function is the converse of the DAYS function.
DATE_SECONDS(seconds) This function returns the date that occurs the given number of seconds after the system base date (17- Nov-1858), in the format DD-MON-YYYY HH:MM:SS.CC. If the return dates time is exactly midnight, this function returns only the date. Given a negative number of seconds, this function returns a delta time string in the format DDDD HH:MM:SS.CC. This function is the converse of the SECONDS function. DATE_TIME(source) Forces IAF to treat the source (which can be text

or numeric), as a date/time value for the purposes of date/time arithmetic. The source must be a valid date/time.
DAYS(source_date) This function returns the number of days that

passed between the system base date (17-Nov-1858) and the given source date (inclusive). The source date must be in the format DD-Mon-YYYY. This function is the converse of the DATE function. Following is an example of the DAYS function in use:
PRINT DAYS(19-Nov-1858)

This example displays the value 2.

DAY_OF_WEEK(source_date) This function returns the day number of

the source date, where Monday is 1, Tuesday is 2, and so on. You must specify the source date in the format DD-Mon-YYYY.
DAYS_IN_MONTH(input-date) This function returns the integer number of days in the month for the specified date. NEXT_MONTH(input-date) This function returns the date corresponding

to the first day of the month following the specified date.

SECONDS(source_date) This function returns the number of seconds

that passed between the system base date (17-NOV- 1858) and the given source date/time (inclusive). The source date must be in the format DDMON- YYYY, and may include a time specification in the format HH:MM:SS.CC. This function returns a floating point number that includes fractions of a second, and therefore facilitates accurately comparing date/times. This function also interprets delta date time. IAF

Built-In Functions IAF 8.0 DML

9-17

Date and Time Functions

returns a negative number of seconds for a delta date time source date. This function is the converse of the DATE_SECONDS function. The following table contains examples of the SECONDS function in use. Example SECONDS(01-JAN-1990 01:10:20.20) SECONDS(0 01:00:00.00) SECONDS(0 02) Result 4137873020.2 -3600 -7200

9-18

Built-In Functions IAF 8.0 DML

Date Arithmetic

Date Arithmetic
The IAF DML language supports date/time arithmetic. Delta time values may also be added to or subtracted from absolute date/time values. 1. 2. 3. 4. 5. You may not add two absolute date/time values together. When absolute date/time values are be subtracted from each other, the result is a delta time. When subtracting one absolute date/time value from another, the smaller date/time must be subtracted from the larger date/time. You may not subtract an absolute date/time from a delta time. When performing date/time arithmetic, at least one of the two operands involved must be a known date/time value. The other can either be another known date/time value, a text string containing an absolute or delta time value, or an integer or floating point number. Integer and floating point numbers are considered to be number of days.

Examples: #a = %TODAY + 7 0: #a = DATE_TIME(31-JAN-1999) - 30-JAN-1999 #a = %TODAY - 7 0: #a = DATE_TIME(31-DEC-1999) - 30.5 #a = %TODAY + 31-JAN-1999 is illegal One of the operands must be a delta time. #a = DATE_TIME(30-JAN-1999) - 31-JAN-1999 is illegal This would produce a negative delta time. #a = DATE_TIME(30-JAN-1999) + 18-NOV-1878 is illegal One of the operands must be a delta time. #a = 7 0: - %TODAY is illegal

Built-In Functions IAF 8.0 DML

9-19

Date Arithmetic

You cannot subtract an absolute date/time from a delta time. #a = %TODAY + -3 is illegal Negative delta times are not permitted. #a = %TODAY - -3 is illegal Negative delta times are not permitted. The IAF DML language recognizes when the comparands in an IF statement are absolute date/time values and then performs date/time comparisons rather than string comparisons. If both comparands in an IF statement are known to be absolute date/time values, they are compared as date/times. If one comparand in an IF statement is known to be an absolute date/time value, but the other is not, IAF converts the other comparand to a date/time. It then performs a date/ time comparison. If the conversion fails, a simple string comparison is done instead. A comparand in an IF statement or an operand in date/time arithmetic is known to be an absolute date/time value if any of the following are true: 1. 2. 3. The comparand is a database field having a datatype of DATE_TIME. The comparand is one of the special variables %NOW, %REPORT_DATE, or %TODAY. The comparand is the result of the DATE() function, the DATE_TIME() function, or the BINARY_TO_POLY() function used with a datatype of ADT. The comparand or operand is a variable that was: Assigned the value of a database field having a datatype of DATE_TIME, YYMMDD, or YYYYMMDD. Assigned the value %NOW, %REPORT_DATE, or %TODAY. Assigned the result of the DATE() function, the DATE_TIME() function, or the BINARY_TO_POLY() function used with a datatype of ADT. Returned from an EXTERNAL routine as a parameter declared as having a datatype of ADT.

4.

9-20

Built-In Functions IAF 8.0 DML

Date Arithmetic

Returned from a stored procedure as a parameter declared as having a datatype of DATE_TIME, YYMMDD, or YYYYMMDD. Passed in from another form and any of the above were true for the value being passed. The DATE_TIME() function can be used to turn a text string containing an absolute date/time value into a known date/time value. An error occurs if the parameter is not a text string containing an absolute date/time value (or an expression that evaluates to one).

Built-In Functions IAF 8.0 DML

9-21

Data Definition Functions

Data Definition Functions

IAF provides data definition functions that enable you to extract metadata pertaining to fields, tables, indices, views, and facilities.

Database Functions
Syntax
The syntax of each database function in the section is:
database_function(database_handle) database_function This is the name of the built-in database function. database_handle This is the handle for the database for which information is desired. The database handle my be a quoted or unquoted literal or a variable. A null string ("") or a variable containing a null string can be used to refer to the default database.

Functions
The following built-in functions enable you to extract metadata pertaining to databases:
DATABASE_DML_HANDLE This function returns the DML handle for

the specified database.

DATABASE_DOMAIN_COUNT This function returns the number of

explicitly defined domains in this database.

DATABASE_ENGINE_ATTRIBUTES This function returns a comma

separated list of engine attributes applicable to this database. The list of all possible engine attributes that can be returned is: AUTO_CURSOR_CLOSE, BIGTEXT, DB_SECURITY, DISTRIBUTED_TRANSACTIONS, GLOBAL_FIELD_SUPPORT, METADATA_BATCH_SUPPORT, MODIFY_SECURITY_LINE, REFLEXIVE_VIEW_ONLY, SECURITY_ACL, SECURITY_ANSI, SINGLE_ATTACH and UNDELETE_SECURITY_LINE.
DATABASE_ENGINE_NAME This function returns the engine name for

the specified database.

9-22

Built-In Functions IAF 8.0 DML

Data Definition Functions

DATABASE_ENGINE_DATATYPES This function returns a comma

separated list containing the names of field data types that are supported by the engine.
DATABASE_FIELD_ATTRIBUTES This function returns a comma

separated list of field attributes applicable to this database. The list of all possible field attributes that can be returned is: CASE_NOCASE_SORT, INITIAL_VALUE, MISSING, MISSING_WITH_VALUE, MULTABLE_INDEX=(DATATYPE, INITIAL, LENGTH, MISSING, SCALE), MUTABLE_TABLE=(DATATYPE, INITIAL, LENGTH, MISSING, SCALE), NAME_SIZE=n, RDB_DATE_FORMAT and UNINITIALIZED_VALUES.
DATABASE_FLAG This function returns a number comprising a bit

mask containing IAF data dictionary internal information.

DATABASE_HELP_LIBRARY This function returns the name of the help library, if any, for the specified database. DATABASE_INDEX_ATTRIBUTES This function returns a comma

separated list of index attributes applicable to this database. The list of all possible index attributes that can be returned is: ASCENDING_AND_DESCENDING, ASCENDING_AND_DESCENDING_SEGMENTS, COMPRESSION, DUPLICATES_ALLOWED, FILLPCT_ADJUSTABLE, HASH_LOCATION_REQUIRED, MAXIMUM_FIELDS=n, NAME_SIZE=n, NODE_SIZE_ADJUSTABLE, PHYSICAL_LOCATION_SIZE=n, STRUCTURE=(CLUSTERED, HASHED, ISAM, SORTED).
DATABASE_LANGUAGE_CODE This function returns the current language code for the specified database. DATABASE_META_BATCH_LEVEL This function returns the current metadata batching level for the specified database. DATABASE_PHYSICAL_NAME This function returns the physical name

of the specified database.

DATABASE_RCI_TR_LEVEL This function returns the current RCI

transaction level for the specified database.

Built-In Functions IAF 8.0 DML

9-23

Data Definition Functions

DATABASE_RCI_TR_MODE This function returns the current RCI

transaction mode for the specified database.

DATABASE_RW_TR_LEVEL This function returns the current read/

write transaction level for the specified database.

DATABASE_RW_TR_MODE This function returns the current read/

write transaction mode for the specified database.

DATABASE_RW_TR_SCOPE This function returns the current read/

write transaction scope for the specified database.

DATABASE_RDB_VERSION This function returns the major and minor

RDBMS version for the specified database.

DATABASE_TABLE_ATTRIBUTES This function returns a comma

separated list of table attributes applicable to this database. The list of all possible table attributes that can be returned is: AUTO_SEG_DELETE, COMPILED_FIELDS_PHYSICALLY_STORED, DISTRIBUTED_LINKS, GEM_TABLE_FIELDS_ONLY, LOCAL_ON_ADD, MAXIMUM_FIELDS=n, MAY_BE_EXTERNAL, MODIFIABLE, NAME_SIZE=n, NO_REDUCED_CAPABILITIES, PHYSICAL_LOCATION, PHYSICAL_LOCATION_SIZE=n, RECORD_ORIENTED, REORDER_WITH_INDEX, TABLE_OBJECT_KEYS, TABLE_REORGS, TABLE_TRANSACTION_CONTROL, VIEW_ON_VIEW and VIRTUAL_CAT_TABLES.
DATABASE_TABLESPACES This function returns a comma separated list containing the names of tablespaces in the database. This information is currently only returned for Oracle databases.

Datatype Functions
Syntax
Following is the syntax format for the index functions that this section describes:
datatype_function([database_handle.]datatype_name) datatype_function This is the name of the built-in datatype function.

9-24

Built-In Functions IAF 8.0 DML

Data Definition Functions

database_handle This is the handle for the database in which the given datatype resides. It is necessary to specify a database handle only if you have invoked more than one database and the specified datatype does not reside in the current default database. datatype_name This is the name of the datatype upon which the given function is to operate.

Functions
The following built-in functions enable you to extract metadata pertaining to user defined datatypes.
DATATYPE_CONVERTED_LENGTH This function returns the length of

the converted datatype. This is only applicable to datatype definitions that specify user datatype conversion functions.
DATATYPE_CONVERTED_SCALE This function returns the scale of

the converted datatype. This is only applicable to datatype definitions that specify user datatype conversion functions.
DATATYPE_FLAG This function returns a number comprising a bit mask

containing IAF data dictionary internal information.

DATATYPE_IMAGE This function returns the file specification of the

user datatype conversion shareable image. This is only applicable to RMS databases.
DATATYPE_INPUT_MASK This function returns the input mask defined for the datatype in the data dictionary. DATATYPE_LENGTH This function returns the length of the user

defined datatype.
DATATYPE_NAME This function returns the name of the user defined

datatype.
DATATYPE_NATIVE This function returns the name of the underlying or

database native datatype on which the user defined datatype is based.

DATATYPE_OUTPUT_MASK This function returns the output mask

defined for the datatype in the data dictionary.

DATATYPE_SCALE This function returns the scale of the user defined

datatype.

Built-In Functions IAF 8.0 DML

9-25

Data Definition Functions

DATATYPE_TO_CONVERTED_ROUTINE This function returns the name of the to converted datatype conversion function for the datatype. This is only applicable to RMS databases. DATATYPE_TO_NATIVE_ROUTINE This function returns the name of

the to native datatype conversion function for the datatype. This is only applicable to RMS databases.
DATATYPE_VALID_VALUES This function returns the valid value(s) defined for the datatype in the data dictionary. DATATYPE_USER_ARGUMENT This function returns the user

argument string for the datatype. This is only applicable to RMS databases.

Facility Functions
Syntax
Following is the syntax format for the facility functions that this section describes:
facility_function([[database_handle.]system_name:]facility_name )

or
facility_function(#variable_name)

facility_function

This is the name of the built-in facility function.

database_handle

In the first syntax format, this is the handle for the database in which the given facility resides. It is necessary to specify a database handle only if you have invoked more than one database, and the specified system and facility do not reside in the current default database.
system_name

In the first syntax format, this is the name of the system that includes the given facility. If you do not specify a system name, IAF uses the system specified via the SET SYSTEM statement. For details on the SET SYSTEM statement, refer to this manuals Language Statements chapter. For details on defining systems, refer to the discussion of the System Definition Editor in the IAF System Reference Manual.

9-26

Built-In Functions IAF 8.0 DML

Data Definition Functions

facility_name

In the first syntax format, this is the name of the facility upon which the given function is to operate. For details on defining facilities, refer to the discussion of the System Definition Editor in the IAF System Reference Manual.
#variable_name

In the second syntax format, this is the name of a variable that indicates the name of the facility upon which the given function is to operate. A database handle may precede the facility name and system name as described on the preceding page. For details on defining systems and facilities, refer to the discussion of the System Definition Editor in the IAF System Reference Manual.

Functions
The following built-in functions enable you to extract metadata pertaining to facilities:
FACILITY_CLASS This function returns the class specified for the given

facility in the data dictionary.

FACILITY_DESCRIPTION This function returns the description specified for the given facility in the data dictionary. FACILITY_DML This function returns the DML code specified for the given facility in the data dictionary. FACILITY_MENU_FILE This function returns the name of the menu file specified for the given facility in the data dictionary. FACILITY_MENU_FORM This function returns the name of the MENU form specified as the entry point for the given facility in the data dictionary. FACILITY_NAME This function returns the name of the given facility.

This function is intended primarily for developers of multi-lingual applications. In a multi-lingual environment, this function returns the local language equivalent of the given facilitys name. For details regarding multi-lingual applications, refer to the IAF guide that applies to your operating system.
FACILITY_SYSTEM This function returns the name of the given system. This function is intended primarily for developers of multi-lingual applications. In a multi-lingual environment, this function returns the

Built-In Functions IAF 8.0 DML

9-27

Data Definition Functions

local language equivalent of the given systems name. For details regarding multi-lingual applications, refer to the IAF guide that applies to your operating system.
FACILITY_TAG This function returns the tag specified for the given

facility in the data dictionary.

Field Functions
Syntax
Following are the syntax formats for the field functions that this section describes:
field_function([database_handle,]table_name,field_name)

or
field_function([table_name,]field_name)

field_function

This is the name of the built-in field function.

database_handle

In the first syntax format, this is the handle for the database in which the given table and field reside. It is necessary to specify a database handle only if you have invoked more than one database, and the specified table and field do not reside in the current default database. You can specify a variable that contains a database handle.
table_name

This is the name of the table in which the given field resides. A table name specification is mandatory in the first syntax format and optional in the second syntax format. A table name specification is mandatory for computed and based on fields and optional for global fields. You can specify a variable that contains a table name.
field_name

This is the name of the field upon which the given function is to operate. You can specify a variable that contains a field name. Note that if the specified field does not exist, the given field functions return value is undefined. Therefore, to avoid problems, use the TABLE_CHECK function as described in this chapters Miscellaneous Functions section to

9-28

Built-In Functions IAF 8.0 DML

Data Definition Functions

check for the fields existence prior to executing the desired field function on the field.

Functions
The following built-in functions enable you to extract metadata pertaining to global, computed, and based on fields:
FIELD_BASED_ON This function returns the name of the global field on which the given field is based. FIELD_CLUSTER This function returns boolean to indicate whether or not the field is part of a cluster. FIELD_DATATYPE This function returns the datatype defined for the

given field in the data dictionary.

FIELD_DEFAULT This function returns the given fields default value. Note that this function does not evaluate any expression whose value is known only at run-time (e.g. %TODAY, %NOW) for a date field. Instead, this function returns the unevaluated string (%TODAY, %NOW). FIELD_DESCRIPTION This function returns the description defined for the given field in the data dictionary. FIELD_FLAG This function returns a comma separated list of field or

table-field flag keywords. The list of all possible field flags that can be returned is: LOWERCASE, REQUIRED, NUMERIC, ZEROFILL, FULLFIELD, POSITIVE, ALPHA, NOZERO and NOTRIM. The list of all possible table-field flags that can be returned is: TRIGGER_STORED, BUFFER_ONLY, READ_ONLY, TRIGGER_EXISTS, TRIGGER_TABLE, TRIGGER_FIELD, TRIGGER_PID, GLOBAL, SYSTEM, COMPUTED, BASED_ON, DBKEY, PID, LAST_PID, CALLBACK_DATATYPE, STATIC, MODIFIED_BASED_ON, AUDIT_MODIFY, AUDIT_ADD, AUDIT_DELETE, CLUSTERED, HIDDEN and STATIC2.
FIELD_HEADING This function returns the heading defined for the

given field in the data dictionary.

FIELD_HELP This function returns the help text for the field or tablefield. The help text is formatted as one long text string that must be

Built-In Functions IAF 8.0 DML

9-29

Data Definition Functions

broken down into individual 60-character lines padded with spaces. The space padding can then be removed from each line using the RTRIM() function.
FIELD_I_LENGTH This function returns the given fields input length. FIELD_I_MASK This function returns the input mask defined for the

given field in the data dictionary.

FIELD_INITIAL_VALUE This function returns the given fields initial

value. The value that this function returns is either a constant or a value symbol (%MISSING, %NOT_MISSING, %USERNAME, or %NOW). For details regarding value symbols, refer to this manuals SPECIAL VARIABLES AND VALUE SYMBOLS chapter.
FIELD_MISSING This function returns the given fields missing value.

Not all database engines support missing values. To determine if a particular database engine with which IAF operates supports missing values, refer to the IAF guide that applies to that database engine. For a topical discussion of missing values, refer to the IAF Users Guide.
FIELD_NAME This function returns the given fields name. This function

is intended primarily for developers of multi- lingual applications. In a multi-lingual system, this function returns the local language equivalent of the given fields name. For details regarding multi-lingual applications, refer to the IAF guide that applies to your operating system.
FIELD_NATIVE This function returns the given fields native datatype as a textual keyword. FIELD_O_LENGTH This function returns the given fields output length. FIELD_O_MASK This function returns the given fields output mask. FIELD_PROMPT This function returns the given fields prompt. FIELD_SCALE This function returns the given fields scale. If the field is a text field, this function returns the fields length. If the field has no defined scale or length, this function returns a zero value. FIELD_SHORT_PROMPT This function returns the fields short prompt. FIELD_SIZE This function returns the given fields physical storage size

in bytes.
FIELD_SOURCE This function returns the given computed fields

source. If you do not specify a table name, IAF displays an error message
9-30 Built-In Functions IAF 8.0 DML

Data Definition Functions

indicating that the field does not exist. If the given field is not a computed field, the function returns a blank.
FIELD_USER_ARGUMENT This function returns the user argument

string for the field or table-field. This is only applicable to RMS databases.
FIELD_VALID_VALUES This function returns the valid value(s) defined for the field in the data dictionary. FIELD_VALIDATION This function returns the given fields DML

validation code.
FIELD_VIEW_BASE This function returns the name of the table field upon which the specified field in the specified view is based, in the format table_name(field_name). If the given table is not a view, or the given field is computed, this function returns a null string ().

Index Functions
Syntax
Following is the syntax format for the index functions that this section describes:
index_function([database_handle.]index_name)

index_function

This is the name of the built-in index function.

database_handle

This is the handle for the database in which the given index resides. It is necessary to specify a database handle only if you have invoked more than one database, and the specified index does not reside in the current default database.
index_name

This is the name of the index upon which the given function is to operate.

Functions
The following built-in functions enable you to extract metadata pertaining to indices:

Built-In Functions IAF 8.0 DML

9-31

Data Definition Functions

INDEX_FIELDS This function returns a comma separated list of the table-field names that make up the index. INDEX_FILL This function returns the index fill value. INDEX_FREE This function retrieves the value given for the /FREE

qualifier.
INDEX_GROW This function retrieves the value given for the /GROW

qualifier.
INDEX_GROWTH_PCT This function retrieves the value given for the / GROWTH_PCT qualifier. INDEX_MAX_EXTENTS This function retrieves the value given for the /

MAX_EXTENTS qualifier.
INDEX_MIN_EXTENTS This function retrieves the value given for the /

MIN_EXTENTS qualifier.
INDEX_ORDER This function returns a comma separated list of the sort

orders for the table-fields that make up the index. Each sort order can either be ASCENDING or DESCENDING.
INDEX_SIZE This function retrieves the value given for the /SIZE

qualifier.
INDEX_STORAGE This function returns the storage area defined for the given index in the data dictionary. INDEX_TABLE This function returns the name of the table associated

with the index.

INDEX_TYPE This function returns the given indexs type (SORTED or HASHED). INDEX_UNIQUE This function returns a TRUE (non-zero) value if the given index is a unique index. Otherwise, this function returns a FALSE (zero) value.

For details regarding indices, refer to the IAF guide that applies to your database engine.

9-32

Built-In Functions IAF 8.0 DML

Data Definition Functions

Table Functions
Syntax
Following is the syntax format for the table functions that this section describes:
table_function([database_handle.]table_name)

table_function

This is the name of the built-in table function.

database_handle

This is the handle for the database in which the given table resides. It is necessary to specify a database handle only if you have invoked more than one database, and the specified table does not reside in the current default database.
table_name

This is the name of the table upon which the given function is to operate.

Functions
The following built-in functions enable you to extract metadata pertaining to tables:
TABLE_ARCHIVABLE This function returns a 1 if the table is archivable

and a 0 if the table is not archivable. Archivable tables have a GEM_ARCHIVE_FLAG column (see Appendix H, IAF Transaction Archiving).
TABLE_DESCRIPTION This function returns the description specified

for the given table in the data dictionary.

TABLE_CLUSTER This function retrieves the name of cluster to which

table is assigned.
TABLE_FIELDS([database-handle.]table-name) This function returns a comma separated list of the table-field names of all the table-fields in the table. TABLE_FILL This function retrieves the value given for the /FILL

qualifier.

Built-In Functions IAF 8.0 DML

9-33

TABLE_FLAGS This function returns a string containing one or both flags that the following table lists and describes. This function uses a comma delimiter when returning both flags.

Flag TRANSACTION_CONTROL

Description The TABLE_FLAGS function returns this flag if the given table is under transaction control (if the table is anything but a virtual table with no transaction control.) The TABLE_FLAGS function returns this flag if the given table is persistent (if the table is anything but a non-persistent virtual table). For details on persistent and non-persistent virtual tables, refer to the IAF Users Guide.

PERSISTENT

TABLE_FREE This function retrieves the value given for the /FREE

qualifier.
TABLE_GROW This function retrieves the value given for the /GROW

qualifier.
TABLE_GROWTH_PCT This function retrieves the value given for the / GROWTH_PCT qualifier. TABLE_IFLAGS([database-handle.]table-name) This function returns

a comma separated list of internal table flag keywords. The current list of internal table flag keywords that may be returned are: STATIC, SYSTEM, VIEW, DIRTY, MULTI_TABLE_VIEW, NOINSERT_DBKEY, ADD_TO_END, OBJECT_KEY, TABLE_KEY, MOD_FLDS_ONLY, TABLE_NO_KEY, VIRTUAL, PERSISTENT, TRANSACTION_CONTROL, NO_TRIGGERS, NO_GEM_FIELDS, DISTRIB_LINK, ADD_SEG_TABLE, REN_SEG_TABLE, DEL_SEG_TABLE, FILLPCT, FREEPCT, NODE_SIZE, GROW_SIZE, GROWTH_PCT, MIN_EXTENTS, MAX_EXTENTS, LOAD_PARAM, 60_FORMAT, ARCHIVE
TABLE_MAX_EXTENTS This function retrieves the value given for the /

MAX_EXTENTS qualifier.

9-34

Built-In Functions IAF 8.0 DML

Data Definition Functions

TABLE_MIN_EXTENTS This function retrieves the value given for the / MIN_EXTENTS qualifier. TABLE_NAME This function returns the name of the given table. This

function is intended primarily for developers of multi-lingual applications. In a multi-lingual system, this function returns the local language equivalent of the given tables name. For details regarding multi-lingual applications, refer to the IAF guide that applies to your operating system.
TABLE_NONPID_FIELDS([database-handle.]table-name) This

function returns a comma separated list of the table-field names of all the non-primary-identifier table-fields in the table.
TABLE_PID This qualifier returns the given tables PID field(s), if any. If there is more than one PID field, this function returns them separated by commas. TABLE_PID_FIELDS([database-handle.]table-name) This function

returns a comma separated list of the table-field names of all the primaryidentifier table-fields in the table.
TABLE_SECURITY This function returns the access rights that the

current user has to the given table. The value that this function returns is a single integer value, where the bit settings correspond to the users access rights. IAF identifies these access rights via the security symbols that the following table lists and describes. Security Symbol %ADMIN_ACCESS %CHANGE_ACCESS %CONTROL_ACCESS %DEFINE_ACCESS %DELETE_ACCESS %ERASE_ACCESS %MODIFY_ACCESS %OPERATOR_ACCESS %READ_ACCESS Access Right User has administrative access to data.. User may modify metadata. User may change security for the given table. User may define new metadata. User may delete the given table. User may delete records. User may update current records. User has operator rights. User has read access to data.

Built-In Functions IAF 8.0 DML

9-35

Data Definition Functions

Security Symbol %SHOW_ACCESS %WRITE_ACCESS

Access Right User may read the given tables metadata (always true). User may add new records.

Following is an example of the TABLE_SECURITY function in use:

IF (TABLE_SECURITY(EMPLOYEES) AND_B %MODIFY_ACCESS) PERFORM MODIFY_EMPLOYEE_DATA ELSE ERROR Insufficient access rights. END_IF

For more information regarding table security, refer to the IAF guide that applies to your database engine.
TABLE_SIZE This function retrieves the vaue given for the /SIZE

qualifier.
TABLE_STORAGE This function retrieves the name of the tablespace in which the table was created. TABLE_TYPE This function returns the value 1 if the given table is a view, 2 if the given table is a virtual table, or 0 otherwise.

View Functions
Syntax
Following is the syntax format for the view function that this section describes:
view_function([database_handle.]view_name)

view_function

This is the name of the built-in view function.

database_handle

This the handle for the database in which the given view resides. It is necessary to specify a database handle only if you have invoked more than one database, and the specified view does not reside in the current default database.
view_name

9-36

Built-In Functions IAF 8.0 DML

Data Definition Functions

This is the name of the view upon which the given function is to operate.

Function
The following built-in function enables you to extract metadata pertaining to views:
VIEW_SOURCE This function returns the views selection source. The

components of a given views selection source include the table(s) upon which the view is based and any record selection criteria (specified via / WITH qualifiers, and so on.)

Miscellaneous Metadata Functions

count = GET_ALL_CLASSES(database-handle [,class-namesarray()] [,class-descriptions-array()]) Given a database handle, this

function returns arrays containing the names and descriptions of all the classes in the database. All pre-existing content in the specified arrays is erased. The number of elements placed into in each array (starting with element number one) is returned as the function result. The databasehandle is a mandatory parameter. All other parameters are optional. The database-handle can be a quoted literal, variable, expression, and so on. A null string can be used to refer to the default database.
count = GET_ALL_DATATYPES(database-handle [,datatype-namesarray()]) Given a database handle, this function returns arrays containing

the names of all the user defined datatypes in the database. All preexisting content in the specified array is erased. The number of elements placed into the array (starting with element number one) is returned as the function result. The database-handle is a mandatory parameter. All other parameters are optional. The database-handle can be a quoted literal, variable, expression, etc. A null string can be used to refer to the default database.
count = GET_ALL_DOMAINS(database-handle [,domain-namesarray()] [,#domain-sources-array()] [,#domain-targets-array()]) Given

a database handle, this function returns arrays containing the names, sources and targets of all explicitly defined domains in the database. All pre-existing content in the specified arrays is erased. The number of elements placed into in each array (starting with element number one) is returned as the function result. The database-handle is a mandatory parameter. All other parameters are optional. The database-handle can be a quoted literal, variable, expression, and so on. A null string can be used to refer to the default database.

Built-In Functions IAF 8.0 DML

9-37

Data Definition Functions

count = GET_ALL_FIELDS(database-handle [,field-names-array()] [,field-descriptions-array()], [,field-datatypes-array()]) Given a

database handle, this function returns arrays containing the names, descriptions and data types of all the global fields in the database. All preexisting content in the specified arrays is erased. The number of elements placed into in each array (starting with element number one) is returned as the function result. The database-handle is a mandatory parameter. All other parameters are optional. The database-handle can be a quoted literal, variable, expression, and so on. A null string can be used to refer to the default database.
count = GET_ALL_FACILITIES(database-handle [,system-namesarray() [,facility-names-array()]) Given a database handle, this function

returns arrays containing the system names and facility names of all facilities in the database. All pre-existing content in the specified arrays is erased. The number of elements placed into in each array (starting with element number one) is returned as the function result. The databasehandle is a mandatory parameter. All other parameters are optional. The database-handle can be a quoted literal, variable, expression, and so on. A null string can be used to refer to the default database.
count = GET_ALL_INDICES(database-handle [,index-names-array()] [,table-names-array()] [,segment-counts-array()]) Given a database

handle, this function returns arrays containing the index names, table names and segment counts of all indices in the database. All pre-existing content in the specified arrays is erased. The number of elements placed into in each array (starting with element number one) is returned as the function result. The database-handle is a mandatory parameter. All other parameters are optional. The database-handle can be a quoted literal, variable, expression, and so on. A null string can be used to refer to the default database.
count = GET_ALL_MESSAGES(database-handle [,message-idarray()] [,message-severity-array()] [,message-text-array()]) Given a

database handle, this function returns arrays containing the message identifiers, severities and message text for all messages in the database. All pre-existing content in the specified arrays is erased. The number of elements placed into in each array (starting with element number one) is returned as the function result. The database-handle is a mandatory parameter. All other parameters are optional. The database-handle can be a quoted literal, variable, expression, and so on. A null string can be used to refer to the default database.

9-38

Built-In Functions IAF 8.0 DML

Data Definition Functions

count = GET_ALL_PARAMETERS(database-handle [,match-string] [,#parameter-names-array()] [,start-dates-array()] [,finish-datesarray()] [,parameter-values-array()] [,parameter-flags-array()]) Given

a database handle, this function returns arrays containing the parameter names, start dates, finish dates, parameter values and parameter flags for all parameters in the database. A wildcard pattern matching string containing the "*" and "%" wildcard pattern matching characters can be specified. Specify a match-string of "" (null string) or "*" to match all parameter names. All pre-existing content in the specified arrays is erased. The number of elements placed into in each array (starting with element number one) is returned as the function result. The databasehandle is a mandatory parameter. All other parameters are optional. The database-handle can be a quoted literal, variable, expression, and so on. A null string can be used to refer to the default database.
count = GET_ALL_PROCEDURES(database-handle [,#procedurenames-array()] [,procedure-descriptions-array()]) Given a database

handle, this function returns arrays containing the procedure names and descriptions of all DML stored procedures in the database. All preexisting content in the specified arrays is erased. The number of elements placed into in each array (starting with element number one) is returned as the function result. The database-handle is a mandatory parameter. All other parameters are optional. The database-handle can be a quoted literal, variable, expression, and so on. A null string can be used to refer to the default database.
count = GET_ALL_SEARCHTAGS(database-handle [,menusearchtags-array()] [,usernames-array()]) Given a database handle,

this function returns arrays containing the menu search tag names and associated usernames of all menu search tags in the database. All preexisting content in the specified arrays is erased. The number of elements placed into in each array (starting with element number one) is returned as the function result. The database-handle is a mandatory parameter. All other parameters are optional. The database-handle can be a quoted literal, variable, expression, and so on. A null string can be used to refer to the default database.
count = GET_ALL_TABLES(database-handle [,selection-string] [,table-names-array()] [,table-descriptions-array()] [,table-flagsarray()]) Given a database handle, this function returns arrays containing

the table names, descriptions and table flags of all tables in the database. All pre-existing content in the specified arrays is erased. The number of elements placed into in each array (starting with element number one) is returned as the function result. The database-handle is a mandatory parameter. All other parameters are optional. The database-handle can be

Built-In Functions IAF 8.0 DML

9-39

Data Definition Functions

a quoted literal, variable, expression, and so on. A null string can be used to refer to the default database.

9-40

Built-In Functions IAF 8.0 DML

Data Definition Functions

The selection-string parameter can be used to limit the types of tables returned. A comma separated list containing any of the following may be specified: "" (null string) ALL PVT TABLE VIEW = The default; same as "ALL" = Select all tables = Select persistent virtual tables = Select regular tables = Select views

count = GET_ALL_TIME_TRIGGERS(database-handle [,time-triggernames-array()] [,time-trigger-descriptions-array()] [,usernamesarray()]) Given a database handle, this function returns arrays containing

the time trigger names, descriptions and associated usernames of all time triggers in the database. All pre-existing content in the specified arrays is erased. The number of elements placed into in each array (starting with element number one) is returned as the function result. The databasehandle is a mandatory parameter. All other parameters are optional. The database-handle can be a quoted literal, variable, expression, and so on. A null string can be used to refer to the default database.
count = GET_ALL_TRIGGERS(database-handle [,tables-namesarray()] [,field-names-array()] [,DML-statements-array()] [,triggerflags-array()]) Given a database handle, this function returns arrays

containing the table names, table-field names, DML statements and trigger flags of all DML triggers in the database. All pre-existing content in the specified arrays is erased. The number of elements placed into in each array (starting with element number one) is returned as the function result. The database-handle is a mandatory parameter. All other parameters are optional. The database-handle can be a quoted literal, variable, expression, and so on. A null string can be used to refer to the default database.

Built-In Functions IAF 8.0 DML

9-41

File Manipulation Functions

File Manipulation Functions

status = DELETE_FILE(filename, default-filename) This function

deletes a file. The condition value from the delete file operation is returned. Odd values are success and even values are failure. The condition value can be translated to an error text string using the ERROR_TEXT function.
FIND_FILE(file_spec[,default_spec]) This function performs a directory scan. The first time this function is called with a unique set of parameters, it returns the filename of the first file that matches the given specification(s). Each subsequent time that this function is called with the same parameters, it returns the filename of the next file that matches the given specification(s). If no file matches the given specification(s), this function returns a null string (). Note that both the file specification (file_spec) and the default specification (default_spec) can include wildcard characters. The following shows an example of the FIND_FILE function in use.
PROCEDURE FORM LOAD_ARRAY BEGIN_BLOCK MAIN_LINE ! The following find_file ensures that the next find_file ! starts afresh. #RESULT=FIND_FILE() #IDX=0 WHILE (1) #RESULT=FIND_FILE(*.dml) IF (#RESULT=) CONTINUE OUT END_IF #IDX=#IDX+1 #FILES(#IDX)=#RESULT END_WHILE END_BLOCK END_FORM

#result = PARSE_FILENAME(filename, default-filename, options)

This function parses a file specification. Use this function to parse a file specification without having to have platform specific knowledge of file specification formatting characters. Filename is the file specification to parse. Default-filename is an optional default file specification to apply to the file specification being parsed. Options is a comma separated list of file specification parsing options as follows:

9-42

Built-In Functions IAF 8.0 DML

File Manipulation Functions

[NO]FULL

Return the entire file specification.

[NO]NODE

Return the node portion of the file specification. Node names within file specifications are an OpenVMS feature and are only applicable to the OpenVMS platform.
[NO]DEVICE

Return the device portion of the file specification.

[NO]DIRECTORY

Return the directory portion of the file specification.

[NO]NAME

Return the file name portion of the file specification.

[NO]TYPE

Return the file type portion of the file specification.

[NO]VERSION

Return the version number portion of the file specification. File version numbers are an OpenVMS feature and are only applicable on the OpenVMS platform.
[NO]CONCEAL

Translate concealed logicals. By default concealed logicals are not translated. Concealed logicals are an OpenVMS feature and are only applicable to the OpenVMS platform.
[NO]SYNTAX_ONLY

Parse the file specification for syntax only and return only the requested portions. Do not fill in missing portions of the file specification by looking at the actual file system. Missing portions of the file specification will only be filled in from the default file specification, if any. NOSYNTAX_ONLY is the default. You must explicitly specify SYNTAX_ONLY whenever you desire a syntax-only parse operation.

Built-In Functions IAF 8.0 DML

9-43

File Manipulation Functions

status = RENAME_FILE(from-file-specification, from-default-filespecification, to-file-specification, to-default-file-specification) This function renames a file. The condition value from the rename file operation is returned. Odd values are success and even values are failure. The condition value can be translated to an error text string using the ERROR_TEXT function.
TEMPORARY_FILENAME(name-string) When given a short "name", this function returns a fully formatted temporary file specification. Use this function to generation file specifications for temporary files without making your program platform specific. In order to ensure that your program will work correctly with all supported IAF DML platforms, you should not use a "name" string longer than 26 characters.

9-44

Built-In Functions IAF 8.0 DML

Miscellaneous Functions

Miscellaneous Functions
#variable = CAST(new-value, keyword-list-string) This is an unsupported function that can be used to directly change the internal polymorphic datatype flag bits of a program variable as well as set the value of the variable. Improper use of this function can cause program failure and data loss.

The value keywords for the comma separated keyword list are: LONG, FLOAT, STRING, DATE, ERROR, STREAM, DFLOAT, SECONDARY, WORD, RAW, PACKED, MP_FLOAT, MP_INTEGER and DELTA.
ERROR_TEXT(error_no,flags) This function returns the error message associated with the given error number (error_no) in the following format:
%FAC-S-NAME, message_text

The following table lists and describes the components of this format: Component FAC S Description This is an indication of the facility in which the error message originated. This is the errors severity indicator, which can be one of the following: E F I S Error Fatal Informational Successful

W Warning NAME message text This the errors defined name. This is error messages descriptive text.

The flags parameter indicates the error message components that the ERROR_TEXT function is to return. The following table lists flag values that can be used individually to cause the ERROR_TEXT function to

Built-In Functions IAF 8.0 DML

9-45

Miscellaneous Functions

return a single component or that can be added together to cause the ERROR_TEXT function to return more than one component. Flag Value 1 2 4 8 Component This value causes the ERROR_TEXT function to return the message text component for the given error. This value causes the ERROR_TEXT function to return the NAME component for the given error. This value causes the ERROR_TEXT function to return the S component (severity indicator) for the given error. This value causes the ERROR_TEXT function to return the FAC component (facility) for the given error.

Following is an example of the ERROR_TEXT function in use:

#ERROR=ERROR_TEXT(%STATUS,3)

This example places in the #ERROR variable the message text and NAME components for the error number that the %STATUS special variable contains.
GET_SCV(scv_string) This function returns the current definition of the System Customization Variable (SCV) that the given string (scv_string) indicates. This function is case-sensitive. If the specified SCVs definition is a search list, this function returns the first element of the list.

Note that on OpenVMS systems, this function returns the definition of the first SCV it finds whose name matches the specified SCV string. Therefore, if the given SCV is defined in the process table, GET_SCV returns the definition given there, regardless of whether it is defined elsewhere. Following are examples of the GET_SCV function in use:
#A=GET_SCV(GEM_CURRENCY) PRINT(GET_SCV(GEM_DATABASE_1))

For details regarding SCVs, refer to the IAF guide that applies your operating system.
IS_MARKED([database_handle,] table_name) This function facilitates

testing for marked table rows. IS_MARKED returns a 1 if the current table row is marked and 0 if it is not marked. The database_handle and

9-46

Built-In Functions IAF 8.0 DML

Miscellaneous Functions

table_name can each be a quoted literals, variables, expressions, etc. It is necessary to specify a database handle only if you have invoked more than one database, and the given table field does not reside in the current default database. This function always operates on the primary stream for the given table. For details on streams, refer to the IAF User Guide. For more information on missing values, refer to the IAF User Guide and the IAF guide that applies to your database engine.
IS_MARKED_ON_STREAM(stream_name, table-name) This function

is identical to the IS_MARKED function except that this function enables you to specify the stream upon which it is to operate (and does not enable you to specify a database handle), whereas the IS_MARKED function always operates on the primary stream for the given table. For details on this functions operation, refer to this sections description of the IS_MARKED function. You can specify the stream name for the IS_MARKED_ON_STREAM function via a variable.
IS_NULL([database_handle.]table_name,field_name) This function facilitates setting and testing for missing values. The table name parameter can be a variable set to a table name.

NOTE: Using a datebase handle, the syntax varies as show below:

IS_NULL([database_handle.]source_modules,source_module)

Likewise, the field name parameter can be a variable set to a field name. It is necessary to specify a database handle only if you have invoked more than one database, and the given source module does not reside in the current default database. When this function is used in an expression, it returns 1 if the given table fields data is missing, or 0 if it is not missing. When this function is to the left of an equal sign, IAF sets the given table fields data to missing if the value to the right of the equal sign is 1, or not missing if the value to the right of the equal sign is 0. Setting a fields value to missing places in the field its specified missing value. If the missing value specified for the AGE field is -1, the following two statements have the same effect (they both set the EMPLOYEES(AGE) fields data to missing):
EMPLOYEES(AGE)=-1 IS_NULL(EMPLOYEES,AGE)=1

Setting a fields data to not missing sets an internal flag indicating that the data is not missing. In a record update situation, the fields contents remain unaltered. In a record add situation, IAF sets the fields value to
Built-In Functions IAF 8.0 DML 9-47

Miscellaneous Functions

null if the field has not had an explicit data assignment. If the missing value specified for the AGE field is -1, the following two statements have the same effect on the datas missing/not missing status (they both set the EMPLOYEES(AGE) fields data to not missing):
EMPLOYEES(AGE)=5 IS_NULL(EMPLOYEES,AGE)=0

This function always operates on the primary stream for the given table. For details on streams, refer to the IAF Users Guide. For more information on missing values, refer to the IAF Users Guide and the IAF guide that applies to your database engine.
IS_NULL_ON_STREAM(stream_name,table_name,field_name)

This function is identical to the IS_NULL function except that this function enables you to specify the stream upon which it is to operate (and does not enable you to specify a database handle), whereas the IS_NULL function always operates on the primary stream for the given table. For details on this functions operation, refer to this sections description of the IS_NULL function. You can specify the stream name for the IS_NULL_ON_STREAM function via a variable.
LTOTAL(break_no,total_column_number) This function returns the

current total value at the specified level break (break_no) for the given column (total_column_number). This function is applicable only to REPORT forms. The first level break is break 1, the second level break is break 2, and so on. Likewise, the first column that includes the /TOTAL block qualifier is total 1, the second column that includes the /TOTAL qualifier is total 2, and so on.
MASK(mask_specification,source_string) This function returns the specified source string masked according to the given mask specification. For details on masks, refer to this manuals INPUT AND OUTPUT MASKS appendix. MESSAGE ([database_handle.]message_name[,argument_1[,argument_2[,...]]])

This function accesses messages defined via the MESSAGES facility in the data dictionary. At run-time, IAF substitutes any data that a given argument specifies for any mask tokens in the message text on a character-by-character basis. It is necessary to specify a database handle only if you have invoked multiple databases, and the specified message does not reside in the current default database. For information regarding messages, refer to the discussion of the MESSAGE statement in this manuals Language Statements chapter.

9-48

Built-In Functions IAF 8.0 DML

Miscellaneous Functions

PARAMETER([database_handle.]parameter_name[,source_date])

When used as part of an expression, this function returns the current value of the specified parameter. When used as part of an assignment, this function causes IAF to update the specified parameter. Because a parameter can be defined via a date range, in addition to a parameter name, you can optionally include a source date after the parameter name. The source date must be in the format DD-Mon-YYYY. It is necessary to specify a database handle only if you have invoked more than one database, and the given parameter does not reside in the current default database. Different transaction controls can exist for a parameter, depending upon its type, as outlined below: For a local parameter with no transaction control, IAF updates only the local copy. For a global parameter with user control, IAF updates the parameter when the transaction commits (when the form exits). For a global parameter with transaction or read only control, or a local parameter with transaction control, IAF updates the parameter when the transaction commits. Following are examples of the PARAMETER function reading parameters:
PRINT PARAMETER(LAST_ORDER_NUMBER) #NAME=PARAMETER(COMPANY_NAME) #MARCH_DISC=PARAMETER(RETAIL_DISC,01-Mar-1992)

Following are examples of the PARAMETER function updating parameters:

PARAMETER(LAST_ORDER_NUMBER)=#NEW_ORDER PARAMETER(RETAIL_DISC,%TODAY)=#TODAYS_SPECIAL

RECORD_ADDRESS(table_spec) This function returns the address of

the record that is currently in the user buffer associated with the specified table. The functions table_spec parameter can be a quoted literal, variable, or expression whose value is a table specification in one of the following formats:
[database_handle.]table_name

or
[stream_name:]table_name

Built-In Functions IAF 8.0 DML

9-49

Miscellaneous Functions

In the first format, database_handle is the handle for the database in which the given table resides. It is necessary to specify a database handle only if you have invoked more than one database, and the specified table does not reside in the current default database. In the second format, stream_name is the name of the stream whose buffer holds the specified tables record. For details regarding record streams and buffers, refer to the IAF Users Guide.
STREAM_DATA (stream_name,table_name,field_name) This

function enables you to use the specified stream to read data from and write data to the given table field. You can use the STREAM_DATA function only from within the file that declares the given stream because stream names are local to a given compilation unit (file). You can specify the stream name, table name and/or field name via variables. Following are examples of the STREAM_DATA function in use:
#FIELD=BALANCE_ + #PERIOD STREAM_DATA(CUST,CUSTOMERS,#FIELD)=#BALANCE + #TRAN_VALUE

This example uses the CUST stream to write to the CUSTOMERS table field that the #FIELD variable specifies.
#DEPT=STREAM_DATA(ADMIN,EMPLOYEES,DEPT_ID)

This example uses the ADMIN stream to read from the EMPLOYEES(DEPT_ID) table field.
TABLE_CHECK([database_handle,]table_name,field_name) This statement enables you to determine if the specified table field exists. If it does exist, this function returns the value symbol %NORMAL. Otherwise, this function returns an error number whose components the ERROR_TEXT function can return.

If you specify a null string () as the table name, this function determines only whether the given field is a global field. If you specify a null string as the field name, this function determines only whether the given table exists. It is necessary to specify a database handle only if you have invoked more than one database, and the specified table does not reside in the current default database. Following are examples of the TABLE_CHECK function in use:
IF (TABLE_CHECK(PARTS,)<>%NORMAL) ERROR PARTS table does not exist END_IF IF (TABLE_CHECK(DF1,CUSTOMERS,ID)<>%NORMAL) ERROR CUSTOMERS(ID) does not exist in DF1 END_IF

9-50

Built-In Functions IAF 8.0 DML

Miscellaneous Functions

For details regarding value symbols, refer to this manuals Special Variables and Value Symbols chapter.
TABLE_DATA([database_handle,]table_name,field_name) This

function allows you to read data from and write data to the given table field. You can specify the table name and the field name via variables. It is necessary to specify a database handle only if you have invoked more than one database, and the specified table field does not reside in the current default database. Following are examples of the TABLE_DATA function in use:
#FIELD=PERIOD_ + #COUNT #TOTAL=#TOTAL + TABLE_DATA(LOG,SALES,#FIELD)

This example reads from the SALES table field that the #FIELD variable specifies.
#FIELD=BIN_ + #COUNT TABLE_DATA(PARTS,#FIELD)=0

This example writes to the PARTS table field that the #FIELD variable specifies.
TOTAL(total_number) This function returns the current total value of

the column that the specified total number indicates. The first column that includes the /TOTAL qualifier is total 1, the second column that includes the /TOTAL qualifier is total 2, and so on. This function applies only to REPORT forms.

Built-In Functions IAF 8.0 DML

9-51

Multibyte Character Set (MBCS) String Manipulation Features

Multibyte Character Set (MBCS) String Manipulation Features

MB_CHR(character-value) This function returns a string containing a

single or multi-byte character corresponding to the specified value. This function can be used to produce a character string containing a single character from either a single byte or multi-byte character set. The setting of the GEM_CHARACTER_SET SCV determines if the current character set is a single or multi-byte character set. The character-value can be a single byte or multi-byte character. The specified character-value is the decimal equivalent of the character's binary encoding in the current character set (as set with the GEM_CHARACTER_SET SCV). A single byte character has a value in the range 0 to 255, a two byte character has a value in the range 0 to 65,535, a three byte character has a value in the range 0 to 16,777,215, and so on. When the current character set is a single byte character set, the value is reduced modulo 256. For example, the value 325 modulo 256 is the same as the value 69.
MB_LEFT(input-string, end-position) This function extracts a

substring from the input-string and returns the result. The substring begins with the first character in the input-string and ends with the character at end-position. This function can be used with character strings containing characters from either single byte or multi-byte character sets. The setting of the GEM_CHARACTER_SET SCV determines if the current character set is a single or multi-byte character set. The end-position is considered to be the number of single or multi-byte characters counting from the start (left side) of the input-string. If the specified end-position is less than one, then a null string is returned. If the specified end-position is greater than the multi-byte length of the input-string, then the entire input-string is returned.
MB_LEN(input-string) This function returns an integer value equal to

the number of characters in the specified input-string.

9-52

Built-In Functions IAF 8.0 DML

Multibyte Character Set (MBCS) String Manipulation Features

This function can be used with character strings containing characters from either single byte or multi-byte character sets. The setting of the GEM_CHARACTER_SET SCV determines if the current character set is a single or multi-byte character set. The returned length is the multi-byte length of the input-string in characters, not the length in bytes. If the input-string is null, then the value zero is returned.
MB_LPAD(input-string, length [,pad-character]) This function returns

a copy of the input-string padded to the specified length with the specified pad character. Padding characters are added to the leading end (left side) of the string. The default pad character is a space character. The optional pad-character string may be specified to cause the string to be padded with a character you specify. Note that only the first character of the padcharacter string is used. This function can be used with character strings containing characters from either single byte or multi-byte character sets. The setting of the GEM_CHARACTER_SET SCV determines if the current character set is a single or multi-byte character set. The length is specified in characters, not bytes.
MB_MID(input-string, starting-position, length) This function extracts

a specified substring from an input-string. This function can be used with character strings containing characters from either single byte or multi-byte character sets. The setting of the GEM_CHARACTER_SET SCV determines if the current character set is a single or multi-byte character set. The starting position and length are specified in characters, not bytes. The position is the one based number of characters starting from the start (left side) of the string. If the position is less than one, then a position of one is assumed. If the position is greater than the multi-byte length of the input-string, then a null string is returned. If the length is less than zero, then a length of zero is assumed and a null string is returned.

Built-In Functions IAF 8.0 DML

9-53

Multibyte Character Set (MBCS) String Manipulation Features

If the length is greater than the number of characters remaining in the string starting at the specified position, then the substring starting at the specified position with a multi-byte length equal to the number of characters remaining in the string is returned.
MB_POS (source-string, sub-string, starting-position) This function

searches for a sub-string within a source-string and returns the sub-string's integer starting character position. This function can be used with character strings containing characters from either single byte or multi-byte character sets. The setting of the GEM_CHARACTER_SET SCV determines if the current character set is a single or multi-byte character set. The starting-position is specified in characters, not bytes. The starting-position is the one based number of characters starting from the beginning (left side) of the source-string. If the specified starting-position is greater than the multi-byte length of the source-string, then the value zero is returned. If the specified starting-position is less than one, then a starting-position of one is assumed. The character position in the source-string at which the sub-string is found is always returned with the following exceptions: If ONLY the sub-string is null and if the specified starting-position is less than or equal to zero, then the value one is returned. If ONLY the sub-string is null and if the specified starting-position is equal to or greater than one and less than or equal to the multibyte length of the source-string, then the specified starting-position is returned. If ONLY the sub-string is null and if the specified starting-position is greater than the multi-byte length of the source-string, then the source string's length plus one is returned. If ONLY the source-string is null, then the value zero is returned. If BOTH the source-string and the sub-string are null, then the value one is returned. If the sub-string cannot be found in the source-string, then the value zero is returned.

9-54

Built-In Functions IAF 8.0 DML

Multibyte Character Set (MBCS) String Manipulation Features

MB_REPLACE(source-string, starting-position, ending-position, replacement-string) This function replaces part of a string with another

string. The substring to be replaced is specified by its starting and ending positions. This function can be used with character strings containing characters from either single byte or multi-byte character sets. The setting of the GEM_CHARACTER_SET SCV determines if the current character set is a single or multi-byte character set. The starting and ending positions are specified in characters rather than bytes and are one based numbers of characters starting from the beginning (left side) of the source-string. If the starting-position is less than one, then it is assumed to be one. If the ending-position is less than one, this it is assumed to be one. If the ending-position is beyond the end of the source-string, then the ending-position is assumed to be the multi-byte length of the sourcestring.
MB_RIGHT(input-string, starting-position) This function extracts a

sub-string from the input-string and returns the result. The substring begins with the character in the specified position and ends with the rightmost (last) character in the input-string. This function can be used with character strings containing characters from either single byte or multi-byte character sets. The setting of the GEM_CHARACTER_SET SCV determines if the current character set is a single or multi-byte character set. The starting-position is specified in characters (not bytes) and is the one based number of characters starting from the beginning (left end) of the input-string. If the specified starting-position is less than one, then the entire inputstring is returned. If the specified starting-position is greater than the multi-byte length of the input-string, then a null string is returned.
MB_RPAD(input-string, length [,pad-character]) This function returns a copy of the input-string padded to the specified length with the specified pad character. Padding characters are added to the trailing end (right side) of the string. The default pad character is an ASCII space. The optional

Built-In Functions IAF 8.0 DML

9-55

Multibyte Character Set (MBCS) String Manipulation Features

pad-character string may be specified to cause the string to be padded with a character you specify. Note that only the first character of the padcharacter string is used. This function can be used with character strings containing characters from either single byte or multi-byte character sets. The setting of the GEM_CHARACTER_SET SCV determines if the current character set is a single or multi-byte character set. The length is specified in characters, not bytes.
MB_SEG(input-string, starting-position, ending-position) This

function extracts a substring from the input-string and returns the result. The substring begins with the character at the specified starting-position ends with the character at the specified ending-position. This function can be used with character strings containing characters from either single byte or multi-byte character sets. The setting of the GEM_CHARACTER_SET SCV determines if the current character set is a single or multi-byte character set. The starting-position is the one based number of characters starting from the beginning (left end) of the string. If the starting-position is less than one, then it is assumed to be one. If the starting-position is greater than the ending-position or the multibyte length of the input-string, then a null string is returned. If the ending position equals the starting position, then a string consisting of the single character at the starting-position is returned. Unless the ending-position is greater than the multi-byte length of the input-string, the multi-byte length of the returned substring equals the ending-position minus the starting-position plus one. If the endingposition is greater than the multi-byte length of the input-string, then a string consisting of all characters from the starting-position to the end of the input-string is returned.
MB_STRING(duplication-count, character-value) This function returns a string consisting of the given single or milti-byte character-value duplicated the number of times that the duplication-count specifies.

This function can be used with character strings containing characters from either single byte or multi-byte character sets. The setting of the

9-56

Built-In Functions IAF 8.0 DML

Multibyte Character Set (MBCS) String Manipulation Features

GEM_CHARACTER_SET SCV determines if the current character set is a single or multi-byte character set. The character-value can be a single byte or multi-byte character. The specified character-value is the decimal equivalent of the character's binary encoding in the current character set (as set with the GEM_CHARACTER_SET SCV). A single byte character has a value in the range 0 to 255, a two byte character has a value in the range 0 to 65,535, a three byte character has a value in the range 0 to 16,777,215, and so on. When the current character set is a single byte character set, the value is reduced modulo 256. For example, the value 325 modulo 256 is the same as the value 69.
MB_VALUE(input-string) This function returns the decimal integer

value of the first character in the string. This function can be used with character strings containing characters from either single byte or multi-byte character sets. The setting of the GEM_CHARACTER_SET SCV determines if the current character set is a single or multi-byte character set. The character-value can be a single byte or multi-byte character. The value returned is the decimal integer equivalent of the character's binary encoding in the current character-set. A single byte character has a value in the range 0 to 255, a two byte character has a value in the range 0 to 65,535, a three byte character has a value in the range 0 to 16,777,215, and so on.

Built-In Functions IAF 8.0 DML

9-57

Environment Variable Functions

Environment Variable Functions

The environment variable functions intentionally have an "_env" suffix rather than an "_scv" suffix. This makes it clear that they operate on environment variables (or logicals on this OpenVMS platform), not System Customization Variables (SCVs). IAF sets the value of an SCV by fetching the value of an environment variable. 1. Some SCVs are fetched only at program startup. This is done because the value of some SCVs needs to be known very early on during program startup. Changing these SCVs during program execution has no affect. Some SCVs are fetched on a just-in-time basis the first time their value is needed. This is done for performance reasons. Changing these SCVs during program execution has an effect if IAF has not already fetched their value; otherwise it has no effect. Still other SCVs are fetched every time they are needed. This is done when the value of the SCV is not needed during program startup and when fetching the SCV value every time it is needed will have no significant effect on performance. Changing these SCVs during program execution is always effective.

2.

3.

These functions change the value of the environment variables from which SCVs are fetched. IAF does not have a centralized SCV caching facility, so it is not possible in general to change IAF SCVs on the fly during program execution unless the SCVs in question fall into category #3 above. Note that the category into which an SCV falls is an internal detail that can change from release to release and is most definitely subject to change without notice.

env_value = GET_CLIENT_ENV(env_name) Returns the value of a

client-side environment variable. Returns an empty string if the program is not running in thin client-server mode. env_name is the name of the environment variable. env_name can be a quoted literal, variable, or expression.

9-58

Built-In Functions IAF 8.0 DML

Environment Variable Functions

env_value = GET_SERVER_ENV(env_name) AKA GET_ENV(env_name) Returns the value of a server-side

environment variable. The GET_SERVER_ENV function is equivalent to the GET_ENV function when running in non-thin client-server mode. env_name is the name of the environment variable. env_name can be a quoted literal, variable, or expression.
env_value_old = SET_CLIENT_ENV(env_name, env_value_new)

Sets the value of a client-side environment variable. Does not set any environment variables and returns an empty string if the program is not running in thin client-server mode. env_name is the name of the environment variable. env_name can be a quoted literal, variable, or expression. env_value_new is the new value to which the environment variable is to be set. env_value_new can be a quoted literal, variable, or expression. env_value_old is the previous value of the environment variable before it was set to the new value.
env_value_old = SET_SERVER_ENV(env_name, env_value_new) AKA SET_ENV(env_name, env_value_new) Sets the value of a server-

side environment variable. The SET_SERVER_ENV function is equivalent to the SET_ENV function when running in non-thin clientserver mode. env_name is the name of the environment variable. env_name can be a quoted literal, variable, or expression. env_value_new is the new value to which the environment variable is to be set. env_value_new can be a quoted literal, variable, or expression. env_value_old is the previous value of the environment variable before it was set to the new value.
report_dir_old = SET_CLIENT_REPORT_DIR(report_dir_new) Sets the value of the thin client's report directory setting. This is the directory to which report listing files are copied when the client has enabled the "copy report listing files to the client" setting. Does not change any client

Built-In Functions IAF 8.0 DML

9-59

Environment Variable Functions

settings and returns an empty string if the program is not running in thin client-server mode. Note that the specified directory is checked for write access before the client's report directory setting is changed. If write access is not permitted, then an error is returned to the DML program and the client's report directory setting remains unchanged. report_dir_new is the new value to which the client's report directory setting is to be set. report_dir_new can be a quoted literal, variable, or expression. report_dir_old is the previous value of the client's report directory setting before it was set to the new value.
report_dir_old = SET_SERVER_REPORT_DIR(report_dir_new) AKA SET_REPORT_DIR(report_dir_new) Sets the value of the thin

server's GEM_REPORT_DIR environment variable. Note that the specified directory is checked for write access before the server's GEM_REPORT_DIR environment variable is changed. If write access is not permitted, then an error is returned to the DML program and the GEM_REPORT_DIR environment variable remains unchanged. report_dir_new is the new value to which the GEM_REPORT_DIR environment variable is to be set. report_dir_new can be a quoted literal, variable, or expression. report_dir_old is the previous value of the GEM_REPORT_DIR environment variable before it was set to the new value.

9-60

Built-In Functions IAF 8.0 DML

Chapter 10

DML Metadata Commands

Introduction

Introduction
You can add, modify, and delete metadata entities via the DML metadata commands that this chapter discusses. Metatdata entities are classes, databases, datatypes, domains, facilities, fields, indices, messages, parameters, stored procedures, tables, time triggers, update triggers, and views. Executing any of the following DML metadata commands commits any transaction in progress prior to performing the metadata operation: ADD INDEX ADD TABLE ADD VIEW DELETE INDEX DELETE TABLE DELETE VIEW MODIFY DATATYPE MODIFY FIELD MODIFY TABLE After these metadata operations the transaction level is zero.
Note: Executing ADD TABLE, MODIFY TABLE or DELETE TABLE on a virtual table is the exception to this rule. If any of these commands are performed on a virtual table, IAF does not commit the transaction and the transaction level remains unaffected.

Note that IAF allows you only to add databases, whereas you can add or delete all other entity types. To modify a view, index, domain, or parameter, you must first delete the given entity and then re--add it with its new definition. In general, you can use variables to specify entity names and qualifier arguments. Unless otherwise noted, you can include a qualifier only once per metadata command. For information regarding the entities that this chapter discusses and any applicable qualifiers that this chapter lists but does not describe, refer to the following IAF documents: IAF System Reference Manual the IAF guide that applies to your database engine the IAF guide that applies to your operating system
10-2 DML Metadata Commands IAF 8.0 DML

ADD CLASS

ADD CLASS
Syntax
ADD CLASS class_name [/qualifiers]

Description
This metadata command allows you to add a class. A class is a label for a group of facilities of similar functionality. For details regarding classes and facilities, refer to the discussion of the System Definition Editor in the IAF System Reference Manual.

Qualifiers
The following qualifiers are valid for use with the ADD CLASS metadata command:

/DESCRIPTION=string_value /REASON=string_expression
This qualifier allows you to specify a string expression indicating the reason for adding the class. If the GEM_META_AUDIT_REASON System Customization Variable (SCV) is set to TRUE, the reason that this qualifier specifies is the default reason that IAF displays in the run--time window that facilitates entering the reason for the metadata change. If the GEM_META_AUDIT_REASON SCV is undefined or set to FALSE, the reason that this qualifier specifies is the reason that IAF stores in the given database. For details regarding the GEM_META_AUDIT_REASON SCV, refer to the IAF guide that applies to your operating system.

Example
ADD CLASS REPORTS /DESCRIPTION=Reports

DML Metadata Commands IAF 8.0 DML

10-3

ADD DATABASE

ADD DATABASE
Syntax
ADD DATABASE database_specification [/qualifiers]

Description
This metadata command allows you to create a relational database. The given database specification identifies the database and is the specification to specify when invoking the database in IAF. For details regarding the database specification format to use with a particular database engine, refer to the IAF guide that applies to that database.

Qualifiers
The following qualifiers are valid for use with the ADD DATABASE metadata command:

/ENGINE=engine_type_keyword
This qualifier allows you to specify the type of database engine for which IAF is to construct the database. Valid engine type keywords are INGRES, ORACLE, RDB, RMS, and SYBASE. The specified database engine must be installed, and must be a database engine that IAF supports on the operating system in use. If the ADD DATABASE metadata command does not include the / ENGINE qualifier, the default engine type is the one that the GEM_DEFAULT_ENGINE System Customization Variable (SCV) specifies. However, note that although SERVER is a valid engine type for use with the GEM_DEFAULT_ENGINE SCV, it is not a valid engine type for use with the ADD DATABASE command. Therefore, if you have the GEM_DEFAULT_ENGINE SCV set to SERVER, the ADD DATABASE command must include the /ENGINE qualifier to specify the type of database engine for which IAF is to construct the database. If the ADD DATABASE command does not include the /ENGINE qualifier, and GEM_DEFAULT_ENGINE is not defined, the default database engine depends upon the operating sytems on which you are currently running. For details regarding the default database engine for a given operating system, refer to the IAF guide that applies to that operating system.

10-4

DML Metadata Commands IAF 8.0 DML

ADD DATABASE

/SECURITY_TYPE=security_type_keyword
This qualifier applies only when using the ADD DATABASE metadata command to create an Rdb database, and indicates the type of security to use for the database. In the syntax above, security_type_keyword can be either ANSI or ACL. If the ADD DATABASE command does not include the / SECURITY_TYPE qualifier when creating an Rdb database, IAF uses ACL security by default. IAF ignores this qualifier if the specified database engine type is not RDB. For details regarding IAFs security facility for Rdb databases, refer to the Guide to Using IAF with Rdb. For details regarding IAFs security facility for any other database type, refer to the IAF guide that applies to that database engine.

/REASON=string_expression
This qualifier allows you to specify a string expression indicating the reason for adding the database. If the GEM_META_AUDIT_REASON SCV is set to TRUE, the reason that this qualifier specifies is the default reason that IAF displays in the run--time window that facilitates entering the reason for the metadata change. If the GEM_META_AUDIT_REASON SCV is undefined or set to FALSE, the reason that this qualifier specifies is the reason that IAF stores in the given database. For details regarding the GEM_META_AUDIT_REASON SCV, refer to the IAF guide that applies to your operating system.

Examples
ADD DATABASE ADDRESSES /ENGINE=RMS ADD DATABASE SUBSCRIPTIONS

DML Metadata Commands IAF 8.0 DML

10-5

ADD DATATYPE

ADD DATATYPE
Syntax
ADD DATATYPE datatype_name [/qualifiers]

Description
This metadata command allows you to add a datatype. Datatypes are the lowest--level description of a data element in a database. All fields are of a particular datatype.

Qualifiers
The following qualifiers are valid for use with the ADD DATATYPE metadata command:

/CONVERTED_LENGTH=numeric_value
This qualifier allows you to specify the length to use for the converted data. Note that this qualifier applies only to the RMS database engine.

/CONVERTED_SCALE=numeric_value
This qualifier allows you to specify the scale to use for the converted data. Note that this qualifier applies only to the RMS database engine.

/CONVERTED_TYPE=effective_datatype
This qualifier allows you to specify the datatype to which to convert the raw data of the datatype that the /NATIVE qualifier specifies. The given datatype must be one of the datatypes in the list on the following page. Note that this qualifier applies only to the RMS database engine.

/IMAGE=string_value
Note that this qualifier applies only to the RMS database engine.

/INPUT_MASK=string_value
This qualifier allows you to specify the input mask to use for the datatype. For details regarding input masks, refer to this manuals INPUT AND OUTPUT masks appendix.

10-6

DML Metadata Commands IAF 8.0 DML

ADD DATATYPE

/LENGTH=numeric_value
This qualifier allows you to specify the length of the raw data.

/NATIVE=native_datatype
This qualifier allows you to specify the physical storage datatype of the raw data that is to be converted to the datatype that the / CONVERTED_TYPE qualifier specifies. The given datatype must be one of the datatypes in the list on the following page.

/OUTPUT_MASK=string_value
This qualifier allows you to specify the output mask to use for the datatype. For details regarding output masks, refer to this manuals INPUT AND OUTPUT masks appendix.

/VALID_VALUES=string_value /REASON=string_expression
This qualifier allows you to specify a string expression indicating the reason for adding the datatype. If the GEM_META_AUDIT_REASON System Customization Variable (SCV) is set to TRUE, the reason that this qualifier specifies is the default reason that IAF displays in the run--time window that facilitates entering the reason for the metadata change. If the GEM_META_AUDIT_REASON SCV is undefined or set to FALSE, the reason that this qualifier specifies is the reason that IAF stores in the given database. For details regarding the GEM_META_AUDIT_REASON SCV, refer to the IAF guide that applies to your operating system.

/SCALE=numeric_value
This qualifier allows you to specify the scale for the raw data.

/TO_CONVERTED_ROUTINE=string_value
This qualifier allows you to specify the name of the routine that converts raw data of the datatype that the /NATIVE qualifier specifies to data of the datatype that the /CONVERTED_TYPE qualifier specifies. Note that this qualifier applies only to the RMS database engine.

/TO_NATIVE_ROUTINE=string_value
This qualifier allows you to specify the name of the routine that converts data of the datatype that the /CONVERTED_TYPE qualifier specifies to

DML Metadata Commands IAF 8.0 DML

10-7

ADD DATATYPE

raw data of the datatype that the /NATIVE qualifier specifies. Note that this qualifier applies only to the RMS database engine.

/USER_ARGUMENT=string_value
Note that this qualifier applies only to the RMS database engine. Following is a list of valid native datatypes and effective datatypes:
BYTE, UBYTENLO D_FLOATNR DATE_TIMENRO DDMMYYNU DDMMYYYYNUMTEXT DOCUMENTARYNZ F_FLOATPACKED G_FLOATQUADWORD H_FLOATTEXT LONGWORD, ULONGWORDVARYING_STRING MMDDYYWORD, UWORD MMDDYYYYYYMMDD NLYYYYMMDD

Note that not all datatypes are valid for all database engines. For details regarding datatypes that are valid for a particular database engine with which IAF operates, refer to the IAF guide that applies to that database engine.

Example
ADD DATATYPE MONEY & /NATIVE=QUADWORD & /SCALE=--2 & /INPUT_MASK=!--@@@@0.00 & /OUTPUT_MASK=!--@@@@0.00

10-8

DML Metadata Commands IAF 8.0 DML

ADD DOMAIN

ADD DOMAIN
Syntax
ADD DOMAIN domain_name [/qualifiers]

Description
This metadata command allows you to add a domain. A domain defines the dynamic set of values that a given field accepts as input. For details on defining domains via the Data Definition Editor, refer to the IAF System Reference Manual. For an in--depth discussion of domains, refer to the IAF Users Guide.

Qualifiers
The following qualifiers are valid for use with the ADD DOMAIN metadata command:

/LINK=source_field_name,target_field_name
This qualifier allows you to specify the field on the source table and the field on the target table, respectively, between which a domain relationship exists. You can specify the /LINK qualifier multiple times to define a multiple field domain.

/REASON=string_expression
This qualifier allows you to specify a string expression indicating the reason for adding the domain. If the GEM_META_AUDIT_REASON System Customization Variable (SCV) is set to TRUE, the reason that this qualifier specifies is the default reason that IAF displays in the run--time window that facilitates entering the reason for the metadata change. If the GEM_META_AUDIT_REASON SCV is undefined or set to FALSE, the reason that this qualifier specifies is the reason that IAF stores in the given database. For details regarding the GEM_META_AUDIT_REASON SCV, refer to the IAF guide that applies to your operating system.

DML Metadata Commands IAF 8.0 DML

10-9

ADD DOMAIN

/SOURCE_TABLE=table_name /TARGET_TABLE=table_name Example

ADD DOMAIN ORDERS_ORDER_LINES & /SOURCE_TABLE=ORDER_LINES & /TARGET_TABLE=ORDER & /LINK=ORDER_NUMBER,ORDER_NUMBER & /LINK=DEPARTMENT,DEPARTMENT

10-10

DML Metadata Commands IAF 8.0 DML

ADD EVENT

ADD EVENT
Syntax
ADD EVENT event_name [/qualifiers]

Description
Adds an event record to the GEM_METADATA_AUDIT table.

Parameters
Event_name

The event name is a required parameter. An unquoted string literal, a quoted string literal or a variable is accepted. Expressions are not accepted. The event name is limited to 65 characters in length.

Qualifiers
/DESCRIPTION=description /PROCESS_NAME=process_name
The description is optional and is blank by default. An unquoted string literal, a quoted string literal or a variable is accepted. Expressions are not accepted. The description is limited to 8192 characters in length. The process name is optional and is blank by default. An unquoted string literal, a quoted string literal or a variable is accepted. Expressions are not accepted. The process name is limited to 16 characters in length.

Example
ADD EVENT PRE_616_UPGRADE & /DESCRIPTION="Before IAF V6.1.6 upgrade" & /PROCESS_NAME="DEVELOPMENT"

ADD EVENT #event & /DESCRIPTION=#description & /PROCESS_NAME=#process_name

DML Metadata Commands IAF 8.0 DML

10-11

ADD FACILITY

ADD FACILITY
Syntax
ADD FACILITY system_name:facility_name [/qualifiers]

Description
This metadata command allows you to add a facility. A facility represents common functionality which is a subset of a system. For details regarding systems and facilities, refer to the discussion of the System Definition Editor in the IAF System Reference Manual.

Qualifiers
The following qualifiers are valid for use with the ADD FACILITY metadata command:

/CLASS=class_name /DESCRIPTION=string_value /DML=(dml_statement) /HELP=string_value

This qualifier allows you to specify a line of help text for the facility. You may specify this qualifier as many times as needed to specify the desired help text message.

/MENU_FORM=string_value /MENU_FILE=string_value /REASON=string_expression

This qualifier allows you to specify a string expression indicating the reason for adding the facility. If the GEM_META_AUDIT_REASON System Customization Variable (SCV) is set to TRUE, the reason that this qualifier specifies is the default reason that IAF displays in the run--time window that facilitates entering the reason for the metadata change. If the GEM_META_AUDIT_REASON SCV is undefined or set to FALSE, the reason that this qualifier specifies is the reason that IAF stores in the

10-12

DML Metadata Commands IAF 8.0 DML

ADD FACILITY

given database. For details regarding the GEM_META_AUDIT_REASON SCV, refer to the IAF guide that applies to your operating system.

/TAG_NAME=string_value Example
ADD FACILITY ACCOUNTS:INVOICE_ENTRY & /CLASS=ENTRY & /TAG_NAME=INV & /DESCRIPTION=Invoice Entry & /DML=(PERFORM AC:INVOICE_ENTRY) & /HELP=Selecting this option will allow you & /HELP=to enter invoices into Accounts Payable

DML Metadata Commands IAF 8.0 DML

10-13

ADD_FACILITY_SECURITY

ADD_FACILITY_SECURITY
Syntax
ADD_FACILITY_SECURITY ([database_handle.]system_name:facility_name, userid, accessvalue)

or
ADD_FACILITY _SECURITY (#variable_name1, #variable_name2, #variable_name3)

Category
Data access

Description
This function adds the requested facility security. If the function is successful, it returns %NORMAL. Otherwise, it returns an error number whose components the ERROR_TEXT function can return.

db_handle
This is the handle for the database in which the given facility resides. It is necessary to specify a database handle only if you have invoked more than one database, and the specified system and facility do not reside in the current default database.

system_name
This is the name of the system that includes the given facility. For details on defining systems, refer to the discussion of the System Definition Editor in the IAF System Reference Manual.

facility_name
This is the name of the facility into which the given security will be added for the specified user. For details on defining facilities, refer to the discussion of the System Definition Editor in the IAF System Reference Manual.

userid
This is the user id for which facility security will be added.

10-14

DML Metadata Commands IAF 8.0 DML

ADD_FACILITY_SECURITY

accessvalue
This is an integer value that represents the privileges to be added into the specified facility. (for example; #acessvalue = %modify_access + %show_access)

#variable_name1
This is the name of the variable that indicates the system that includes the given facility. It is followed by the name of the facility for which the specified security values will be added for the specified user. A database_handle may precede the system name. For details on defining systems and facilities, refer to the discussion of the System Definition Editor in the IAF System Reference Manual.

#variable_name2
This is the name of the variable that indicates the user id for which the specified facility security values will be added.

#variable_name3
This is the name of the variable that indicates integer value that represents the privileges to be added into the specified facility. for example, #acessvalue = %modify_access + %show_access

Example 1
Procedure_form main ! The following example adds security entry for user jim with ! %execute_access to system sys1 and facility f1 in videos ! database #access = %execute_access #ret = ADD_FACILITY_SECURITY( videos.sys1:f1, jim, #access ) End_form

DML Metadata Commands IAF 8.0 DML

10-15

ADD_FACILITY_SECURITY

Example 2
Procedure_form main ! The following example adds security entry for user jim with ! %execute_access and %show_access to system sys1 and ! facility f1 in videos database #db_fac = "videos.sys1:f1" #user = "jim" #access = %execute_access + %show_access #ret = ADD_FACILITY_SECURITY( #db_fac, #user, #access ) End_form

10-16

DML Metadata Commands IAF 8.0 DML

ADD FIELD

ADD FIELD
Syntax
ADD FIELD field_name [/qualifiers]

Description
This metadata command allows you to add a field.

Qualifiers
The following qualifiers are valid for use with the ADD FIELD metadata command:

/DATATYPE=datatype
This qualifier allows you to specify the fields datatype. The /DATATYPE qualifier can specify a native datatype or a user--defined datatype. For details regarding native and user--defined datatypes for a particular database engine, refer to the IAF guide that applies to that database engine.

/DEFAULT=string_value /DESCRIPTION=string_value /DOMAIN=string_value

See /DOMAIN on page 5-48.

/FLAGS=flag_value[,flag_value[,...]]
This qualifier allows you to specify one or more of the following flag values: NONE, LOWERCASE, REQUIRED, NUMERIC, ZEROFILL, FULL, POSITIVE, ALPHA, NOZERO. For details regarding these flag values, refer to the discussion of the Data Definition Editor in the IAF guide that applies to the database engine in use.

DML Metadata Commands IAF 8.0 DML

10-17

ADD FIELD

/HEADING=string_value /HELP=string_value
This qualifier allows you to specify a line of help text for the field. You may specify this qualifier as many times as needed to specify the desired help text message.

/INITIAL_VALUE=string_expression
This qualifier allows you to specify the initial value for the field. The initial value can be a constant value or one of the special keywords that the following table lists and describes. Keyword %MISSING Description This keyword indicates that the fields initial value is to be the missing value. Note that not all database engines support missing values. To determine if a particular IAF--supported database engine supports missing values, refer to the IAF guide that applies to that database engine. This is the default initial value on database engines that support missing values. This keyword indicates that the fields initial value is to be zero for numeric fields or a null string () for non--numeric fields. This is the default initial value on database engines that do not support missing values. This keyword indicates that the fields initial value is to be the date and time at which the record in which the field resides was added, and should be used for fields of a DATE_TIME datatype. It can also be used on fields of a TEXT datatype (IAF stores the data in the format YYYYMMDDHHMMSSCC). This keyword indicates that the fields initial value is to be the username associated with the process that is adding the record in which the field resides, and should be used only for fields of a TEXT datatype.

%NOT_MISSIN G

%NOW

%USERNAME

Note that to IAF, the constructs /INITIAL_VALUE=%NOW and / INITIAL_VALUE=%NOW are equivalent (i.e. enclosing the keyword in quotes does not affect the definition of the initial value).

10-18

DML Metadata Commands IAF 8.0 DML

ADD FIELD

/INPUT_MASK=string_value
This qualifier allows you to specify the input mask to use for the field. For details regarding input masks, refer to this manuals INPUT AND OUTPUT masks appendix.

/LENGTH=numeric_value /MISSING=string_value /OUTPUT_MASK=string_value

This qualifier allows you to specify the output mask to apply to the fields output data. For details regarding output masks, refer to this manuals INPUT AND OUTPUT masks appendix.

/PROMPT=string_value /REASON=string_expression
This qualifier allows you to specify a string expression indicating the reason for adding the field. If the GEM_META_AUDIT_REASON System Customization Variable (SCV) is set to TRUE, the reason that this qualifier specifies is the default reason that IAF displays in the run--time window that facilitates entering the reason for the metadata change. If the GEM_META_AUDIT_REASON SCV is undefined or set to FALSE, the reason that this qualifier specifies is the reason that IAF stores in the given database. For details regarding the GEM_META_AUDIT_REASON SCV, refer to the IAF guide that applies to your operating system.

/SCALE=numeric_value /SHORT_PROMPT=string_value /USER_ARGUMENT=string_value /VALIDATION=dml_string_value Example

ADD FIELD CUSTOMER_NAME /DATATYPE=TEXT & /LENGTH=30 & /DESCRIPTION=Customer Name & /PROMPT=Customer Name & /HEADING=Customer,Name

DML Metadata Commands IAF 8.0 DML

10-19

ADD INDEX

ADD INDEX
Syntax
ADD INDEX index_name [/qualifiers]

Description
This metadata command allows you to add an index. You can define any number of indices for a table. For information on defining indices via the Data Definition Editor, refer to the IAF guide that applies to the database engine in use.

Qualifiers
The following qualifiers are valid for use with the ADD INDEX metadata command:

/FIELD=field_name
This qualifier allows you to specify a field that is to be an index field. The ADD INDEX command can specify this qualifier once for each index field, or can use this qualifier in conjunction with the / FIELD_ASCENDING and/or /FIELD_DESCENDING qualifiers. If the ADD INDEX metadata command uses this qualifier to specify the last or only index field, the index will be in ascending order.

/FIELD_ASCENDING=field_name
This qualifier allows you to specify a field that is to be an index field. The ADD INDEX command can specify this qualifier once for each index field, or can use this qualifier in conjunction with the /FIELD and/or / FIELD_DESCENDING qualifiers. If the ADD INDEX metadata command uses this qualifier to specify the last or only index field, the index will be in ascending order.

/FIELD_DESCENDING=field_name
This qualifier allows you to specify a field that is to be an index field. The ADD INDEX command can specify this qualifier once for each index field, or can use this qualifier in conjunction with the /FIELD and/or / FIELD_ASCENDING qualifiers. If the ADD INDEX metadata command uses this qualifier to specify the last or only index field, the index will be in descending order.
10-20 DML Metadata Commands IAF 8.0 DML

ADD INDEX

/FILL=percentage_fill /FREE=percent_amount
This qualifier corresponds to the PCTFREE ORACLE keyword and allows the user to provide a numeric percentage value. Note that this qualifier only applies to the ORACLE database engine.

/GROW=number_bytes
This qualifier corresponds to the INITIAL ORACLE keyword and allows the user to provide a numeric value for the size of the next data block. Note that this qualifier only applies to the ORACLE database engine.

/GROWTH=percent_amount
This qualifier corresponds to the PCTINCREASE ORACLE keyword and allows the user to provide a percentage value for the increase in size of additional data block(s) relative to the size of the previously allocated block. Note that this qualifier only applies to the ORACLE database engine.

/MAX_EXTENTS=integer_value
This qualifier corresponds to the MAXEXTENTS ORACLE keyword and allows the user to indicate the maximum size for the index data area. Note that this qualifier only applies to the ORACLE database engine.

/MIN_EXTENTS=integer_value
This qualifier corresponds to the MINEXTENTS ORACLE keyword and allows the user to indicate a minimum size for the index data area. Note that this qualifier only applies to the ORACLE database engine.

/NODUPLICATES or /DUPLICATES /REASON=string_expression

This qualifier allows you to specify a string expression indicating the reason for adding the index. If the GEM_META_AUDIT_REASON System Customization Variable (SCV) is set to TRUE, the reason that this qualifier specifies is the default reason that IAF displays in the run--time window that facilitates entering the reason for the metadata change. If the GEM_META_AUDIT_REASON SCV is undefined or set to FALSE, the reason that this qualifier specifies is the reason that IAF stores in the given database. For details regarding the

DML Metadata Commands IAF 8.0 DML

10-21

ADD INDEX

GEM_META_AUDIT_REASON SCV, refer to the IAF guide that applies to your operating system.

/SIZE=number_bytes
This qualifier corresponds to the INITIAL ORACLE keyword and allows the user to provide a numeric value for the size of the initial data block. Note that this qualifier only applies to the ORACLE database engine.

/SIZE=node_size /STORAGE_AREA=storage_area_name /TABLE=table_name /TYPE=index_type_keyword

This qualifier allows you to specify a keyword indicating the type of index to create. Valid keywords for use with this qualifier are HASHED and SORTED. For details regarding index types, refer to the IAF guide that applies to the database engine in use.

Example:
ADD INDEX ORDER_LINES & /TABLE=ORDER_LINES & /NODUPLICATES & /FIELD=ORDER_NUMBER & /FIELD=LINE_NUMBER

ORACLE Example:
ADD INDEX T1_IDX & /TABLE=T1 & /FIELD=TXT & /SIZE=10240 & /GROW=6144 & /GROWTH_PCT=60 & /FREE=20 & /MIN_EXTENTS=1 & /MAX_EXTENTS=100 & /STORAGE_AREA=GEMDEV

10-22

DML Metadata Commands IAF 8.0 DML

ADD MANAGER_ROLE

ADD MANAGER_ROLE
Syntax
ADD MANAGER_ROLE[user_name:role_name]

Category
Program Flow

Description
This command works similarly to ADD USERS_ROLE. Adds an entry to table GEM_ROLE_USERS with identification M in GEM_USER_TYPE column, which means Manager of role just added.

Example
ADD MANAGER_ROLE dinats:DEV,USERS

Adds roles DEV, USERS to dinats as Manager of the roles.

DML Metadata Commands IAF 8.0 DML

10-23

ADD MESSAGE

ADD MESSAGE
Syntax
ADD MESSAGE message_name [/qualifiers]

Description
This metadata command allows you to add an application message. IAF displays the messages text upon executing a MESSAGE statement that specifies the message. For details on defining messages via the Data Definition Editor, refer to the IAF System Reference Manual. For details regarding the MESSAGE statement, refer to its description in this manuals LANGUAGE STATEMENTS chapter.

Qualifiers
The following qualifiers are valid for use with the ADD MESSAGE metadata command:

/REASON=string_expression
This qualifier allows you to specify a string expression indicating the reason for adding the message. If the GEM_META_AUDIT_REASON System Customization Variable (SCV) is set to TRUE, the reason that this qualifier specifies is the default reason that IAF displays in the run--time window that facilitates entering the reason for the metadata change. If the GEM_META_AUDIT_REASON SCV is undefined or set to FALSE, the reason that this qualifier specifies is the reason that IAF stores in the given database. For details regarding the GEM_META_AUDIT_REASON SCV, refer to the IAF guide that applies to your operating system.

/SEVERITY=severity_code
This qualifier allows you to specify a code indicating the severity of the message you are adding. Valid severity codes for use with this qualifier are ERROR, FATAL, INFORMATIONAL, SUCCESS, and WARNING. If you do not specify a severity code via the /SEVERITY qualifier, IAF uses ERROR as the default severity code.

10-24

DML Metadata Commands IAF 8.0 DML

ADD MESSAGE

/TEXT=string_value
This qualifier allows you to specify the text of the message you are adding.

Examples
ADD MESSAGE INVALID_DIV & /SEVERITY=ERROR & /TEXT=Division !Tax is Invalid ADD MESSAGE ROUTE_WARNING & /SEVERITY=WARNING & /TEXT=Route !As is overloaded

DML Metadata Commands IAF 8.0 DML

10-25

ADD PARAMETER

ADD PARAMETER
Syntax
ADD PARAMETER parameter_name [/qualifiers]

Description
This metadata command allows you to add a parameter. Parameters are global or local system variables. For details regarding parameters, refer to the discussion of the Data Definition Editor in the IAF System Reference Manual.

Qualifiers
The following qualifiers are valid for use with the ADD PARAMETER metadata command:

/ADD_VALUE=start_date,finish_date,string_value
This qualifier allows you to specify the value for a date controlled parameter. Specify the start date and end date in the format DD--MON-YYYY. For a parameter that is not date--controlled, use the /VALUE qualifier instead of this qualifier.

/FLAGS=flag_value[,flag_value[,...]]
This qualifier allows you to specify one or more of the following flag values: GLOBAL, LOCAL, NODATES, READ_ONLY, TRANSACTION_CONTROL, USER_CONTROL. For details regarding these flag values, refer to the discussion of the Data Definition Editor in the IAF System Reference Manual.

/REASON=string_expression
This qualifier allows you to specify a string expression indicating the reason for adding the parameter. If the GEM_META_AUDIT_REASON System Customization Variable (SCV) is set to TRUE, the reason that this qualifier specifies is the default reason that IAF displays in the run--time window that facilitates entering the reason for the metadata change. If the GEM_META_AUDIT_REASON SCV is undefined or set to FALSE, the reason that this qualifier specifies is the reason that IAF stores in the given database. For details regarding the

10-26

DML Metadata Commands IAF 8.0 DML

ADD PARAMETER

GEM_META_AUDIT_REASON SCV, refer to the IAF guide that applies to your operating system.

/VALUE=string_value
This qualifier allows you to specify the value for a parameter that is not date--controlled. For a date controlled parameter, use the /ADD_VALUE qualifier instead of this qualifier.

Examples
ADD PARAMETER INFLATION_RATE & /FLAGS=GLOBAL, READ_ONLY & /ADD_VALUE=01--JAN--1990, 31--DEC--1990,12.1& /ADD_VALUE=01--JAN--1991, 31--DEC--1991,14.1 ADD PARAMETER COMPANY_NAME & /FLAGS=GLOBAL,READ_ONLY,NODATES & /VALUE=ABC Motor Corporation

DML Metadata Commands IAF 8.0 DML

10-27

ADD PROCEDURE

ADD PROCEDURE
Syntax
ADD PROCEDURE procedure_name [/qualifiers]

Description
This metadata command allows you to add a stored procedure to the database. Stored procedures are typically PROCEDURE forms containing DML code that IAF executes within the context of a stored procedure Server. A Client that connects to the Server via the DML CONNECT statement causes the Server to operate as a stored procedure Server. For details on defining stored procedures via the Data Definition Editor, refer to the IAF System Reference Manual. For details on IAFs Client-- Server environment, refer to the IAF Users Guide. For details on the CONNECT statement, refer to this manuals LANGUAGE STATEMENTS chapter.

NOTE:
All IAF predefined stored procedure names begin with GEM_. Therefore, IAF does not permit user--defined stored procedure names to begin with GEM_. For details regarding predefined stored procedures, refer to this manuals PREDEFINED STORED PROCEDURES appendix.

Qualifiers
The following qualifiers are valid for use with the ADD PROCEDURE metadata command:

/DATA_ELEMENT=element_name [/data_element_qualifiers] /DESCRIPTION=string_value

10-28

DML Metadata Commands IAF 8.0 DML

ADD PROCEDURE

/FACILITY=system-name:facility-name
This qualifier specifies
1. The name of a facility that a user must have access to at runtime in order to execute the stored procedure, and A facility from which the file-name and form-name will be defaulted at run-time if the stored procedure definition does not specify them.

2.

The user must have EXECUTE access to the specified facility in order to execute the stored procedure. This check takes place if the stored procedure is executed via the EXECUTE statement or via IAF Connect. If no facility is specified, then no security check will take place and any user will be able to execute the stored procedure without restriction. The specified system-name and facility-name are not validated and need not even exist in the database at the time the stored procedure definition is added to the database. It can be added later. Please note that the systemname is required and cannot be defaulted. Facility security is only checked when USER stored procedures are executed. It is not checked for either internal or built-in stored procedures, which are not defined in the database and therefore cannot have facilities associated with them. Since both the facility metadata and the stored procedure metadata may specify a form-file and form-name to be executed it is necessary to define which takes precedence. The stored procedure metadata takes precedence. The form-file and form-name from the facility metadata is only used if the stored procedure metadata does not specify them.

/FILE_NAME=string_value
This qualifier specifies a string indicating the physical location and name of the file in which the form that contains the DML procedure code resides.

/FORM_NAME=string_value /PARAMETER=element_name [/parameter_qualifiers] /REASON=string_expression

This qualifier allows you to specify a string expression indicating the reason for adding the procedure. If the GEM_META_AUDIT_REASON
DML Metadata Commands IAF 8.0 DML 10-29

ADD PROCEDURE

System Customization Variable (SCV) is set to TRUE, the reason that this qualifier specifies is the default reason that IAF displays in the run--time window that facilitates entering the reason for the metadata change. If the GEM_META_AUDIT_REASON SCV is undefined or set to FALSE, the reason that this qualifier specifies is the reason that IAF stores in the given database. For details regarding the GEM_META_AUDIT_REASON SCV, refer to the IAF guide that applies to your operating system.

Parameter Qualifiers
You can include the following qualifiers after the /PARAMETER qualifier to further describe the given parameter:

/DATATYPE=datatype_name /LENGTH=numeric_value /SCALE=numeric_value /PASS=VALUE|REFERENCE

Data Element Qualifiers

You can include the following qualifiers after the /DATA_ELEMENT qualifier to further describe the given data element:

/DATATYPE=datatype_name /LENGTH=numeric_value /SCALE=numeric_value Example

ADD PROCEDURE CUSTOMER_LOOKUP & /DESCRIPTION=Customer Credit Lookup & /FILE_NAME=APP:CUST_LOOKUP & /PARAMETER=CUSTOMER_ID & /DATATYPE=TEXT & /LENGTH=6 & /PASS=VALUE & /PARAMETER=CUSTOMER_NAME & /DATATYPE=TEXT & /LENGTH=30 & /PASS=REFERENCE & /PARAMETER=CREDIT_LIMIT &

10-30

DML Metadata Commands IAF 8.0 DML

ADD PROCEDURE

/DATATYPE=G_FLOAT & /PASS=REFERENCE

DML Metadata Commands IAF 8.0 DML

10-31

ADD ROLE_MANAGER

ADD ROLE_MANAGER
Syntax
ADD ROLE_MANAGER[role_name:user_name]

Category
Program Flow

Description
This command works similarly to ADD ROLE_USERS. Adds an entry to table GEM_ROLE_USERS with identification M in GEM_USER_TYPE column, which means Manager of role just added.

Example
ADD ROLE_MANAGER DEV: dinats,lisa

Adds users dinats, lisa to role DEV as Managers of the role.

10-32

DML Metadata Commands IAF 8.0 DML

ADD TABLE

ADD TABLE
Syntax
ADD TABLE table_name [/qualifiers]

Description
This metadata command allows you to add a new table to the database. A table is a matrix where each row represents a record, and each column represents a field.

Qualifiers
The following qualifiers are valid for use with the ADD TABLE metadata command:

/ADD_FIELD=global_field_name
or

/ADD_FIELD=local_field_name BASED_ON global_field_name [/field_detail_qualifiers]

or

/ADD_FIELD=local_field_name COMPUTED_BY (computed_expression) [/field_detail_qualifiers]

This qualifier allows you to specify a field that is to be in the table you are adding. Specify this qualifier once for each field that is to be in the table. The first format above specifies a global field. The second format specifies a field that is based on a global field. The third format specifies a computed field. When specifying a based on or computed field, you may use field detail qualifiers to specify the fields attributes. For information on field detail qualifiers, refer to this sections Field Detail Qualifiers heading. For details on global, based on, and computed fields, refer to the discussion of the Data Definition Editor in the IAF guide that applies to the database engine in use.

DML Metadata Commands IAF 8.0 DML

10-33

ADD TABLE

/ARCHIVE
Make the newly added table archivable for use with Transaction Archiving (see Appendix H, IAF Transaction Archiving). This has the effect of adding a GEM_ARCHIVE_FLAG column to the table. The GEM_ARCHIVE_FLAG column is used by the MARK, UNMARK and ARCHIVE statements as well as the IS_MARKED() and IS_MARKED_ON_STREAM() functions.

/CLUSTER
This is a sub-qualifier to the /ADD_FIELD qualifier to tag the fields which are part of the cluster. Note that this qualifier only applies to the ORACLE database engine.

Example Useage:
/ADD FIELD=fieldname CLUSTER

Example:
ADD TABLE T1 & /CLUSTER=C1 & /ADD_FIELD=QW CLUSTER & /ADD_FIELD=STR CLUSTER BASED_ON TXT & /ADD_FIELD=VT & /ADD_FIELD=ADT CLUSTER & /ADD_FIELD=Q2 COMPUTED_BY (T1 (QW) * 2)

Note that only global or based on fields may be clustered.

/CLUSTER=cluster_name
This qualifier is used to identy the cluster to which the table be added is to be included. Note that this qualifier only applies to the ORACLE database engine.

/DESCRIPTION=string_value /FILL=percent_amount
This qualifier corresponds to the PCTUSED ORACLE keyword and allows the user to provide a numeric percentage value. Note that this qualifier only applies to the ORACLE database engine.

/FREE=percent_amount
This qualifier corresponds to the PCTFREE ORACLE keyword and allows the user to provide a numeric percentage value. Note that this qualifier only applies to the ORACLE database engine.

10-34

DML Metadata Commands IAF 8.0 DML

ADD TABLE

GROW=number_of_bytes
This qualifier corresponds to the NEXT ORACLE keyword and allows the user to provide a numeric value for the size of the next data block. Note that this qualifier only applies to the ORACLE database engine.

GROWTH_PCT=percent_amount
This qualifier corresponds to the PCTINCREASE ORACLE keyword and allows the user to provide a percentage value for the increase in size of additional data block(s) relative to the size of the previously allocated block. Note that this qualifier only applies to the ORACLE database engine.

/LOCATION=string_value
This qualifier allows you to specify a string indicating the name and location of the tables datafile. Note that this qualifier applies only to the RMS database engine.

/MIN_EXTENTS=integer_value
This qualifier corresponds to the MINEXTENTS ORACLE keyword and allows the user to indicate a minimum size for the tables data area. Note that this qualifier only applies to the ORACLE database engine.

/MAX_EXTENTS=integer_value
This qualifier corresponds to the MAXEXTENTS ORACLE keyword and allows the user to indicate a maximum size for the tables data area. Note that this qualifier only applies to the ORACLE database engine.

/NOARCHIVE
The table is not archivable. This is the default.

/REASON=string_expression
This qualifier allows you to specify a string expression indicating the reason for adding the table. If the GEM_META_AUDIT_REASON System Customization Variable (SCV) is set to TRUE, the reason that this qualifier specifies is the default reason that IAF displays in the run--time window that facilitates entering the reason for the metadata change. If the GEM_META_AUDIT_REASON SCV is undefined or set to FALSE, the reason that this qualifier specifies is the reason that IAF stores in the given database. For details regarding the GEM_META_AUDIT_REASON SCV, refer to the IAF guide that applies to your operating system.
DML Metadata Commands IAF 8.0 DML 10-35

ADD TABLE

/SIZE=number_of_bytes
This qualifier corresponds to the INITIAL ORACLE keyword and allows the user to provide a numeric value for the size of the initial data block. Note that this qualifier only applies to the ORACLE database engine.

/STATIC
This qualifier indicates that the table that the ADD TABLE metadata command is defining is a static table. In effect, a static table is a template for data in an existing datafile. Typically, the datafile is used by one or more applications external to IAF. Any changes to a static tables metadata (i.e. field definitions) changes only the way IAF views the existing data (IAF makes no structural changes that would impact any non--IAF applications using the given data). Note that this qualifier applies only to the RMS database engine. For more information regarding static tables, refer to the Guide to Using IAF with RMS.

/STOREAGE_AREA=tablespace
This qualifier is used to identify the tablespace in which to create the new table. Note that this qualifier only applies to the ORACLE database engine.

/VIRTUAL[=PERSISTENT[,TRANSACTION_CONTROL]]
This qualifier indicates that the table is to be a virtual table. Including the PERSISTENT keyword indicates that the table is to be a persistent virtual table (i.e. it is to continue to exist between invocations). Including the TRANSACTION_CONTROL keyword indicates that the table is to be under transaction control. For details on virtual tables and transactions, refer to the IAF Users Guide.

Field Detail Qualifiers

You can include the following field detail qualifiers after each /ADD_FIELD qualifier that specifies a based on or computed field to specify the given fields details (for example; attributes):

10-36

DML Metadata Commands IAF 8.0 DML

ADD TABLE

/DESCRIPTION=string_value /HEADING=string_value /HELP=string_value

This qualifier allows you to specify a line of help text for the field. You may specify this qualifier as many times as needed to specify the desired help text message.

/INPUT_MASK=string_value
This qualifier allows you to specify the input mask to use for the field. For details regarding input masks, refer to this manuals INPUT AND OUTPUT masks appendix.

/OUTPUT_MASK=string_value
This qualifier allows you to specify the output mask to use for the field. For details regarding output masks, refer to this manuals INPUT AND OUTPUT masks appendix.

/POSITION=numeric_value
This qualifier allows you to specify the given fields offset, based on a starting offset of zero (i.e. the tables first field has an offset of zero). Note that this qualifier applies only to static tables when using the RMS database engine. For details regarding static table, refer to the Guide to Using IAF with RMS.

/PROMPT=string_value /SHORT_PROMPT=string_value Example

ADD TABLE ORDER_LINES & /DESCRIPTION=Order Lines & /ADD_FIELD=ORDER_NUMBER & /ADD_FIELD=LINE BASED_ON SEQUENCE & /ADD_FIELD=QUANTITY & /ADD_FIELD=UNIT_COST & /ADD_FIELD=LINE_VALUE COMPUTED_BY & (ORDER_LINES(QUANTITY)*ORDER_LINES(UNIT_COST)) & /DESCRIPTION=Line Value & /HEADING=Line,Value & /PROMPT=Line Value & /OUTPUT_MASK=!--@@@,@@0.0@

DML Metadata Commands IAF 8.0 DML

10-37

ADD_TABLE_SECURITY

ADD_TABLE_SECURITY
Syntax
ADD_TABLE_SECURITY ([database_handle.]table_name, userid, accessvalue,[grant_option])

or
ADD_TABLE_SECURITY (#variable_name1, #variable_name2, #variable_name3, [#variable_name4])

Category
Data Access

Description
This function adds the requested table security. If the function is successful, it returns %NORMAL. Otherwise, it returns an error number whose components the ERROR_TEXT function can return.

database_handle
This is the handle for the database in which the given table resides. It is necessary to specify a database handle only if you have invoked more than one database, and the specified table does not reside in the current default database. If the database_handle is indicated, the database_handle and the table_name have to be enclosed in quotes (see examples below.)

table_name
This is the name of the table for which the specified security values will be added for the specified user.

userid
This is the user id for which the specified table security values will be added.

accessvalue
This is an integer value that represents the privileges to be added to the specified table.

10-38

DML Metadata Commands IAF 8.0 DML

ADD_TABLE_SECURITY

(for example; acessvalue = %modify_access + %read_access)

grant_option
This is an optional parameter. If present, its value ('Y 'or 'N') will be added to the specified user, if applicable ( only databases with ANSI security have this option ). If not present, its default value is 'N'. This is not applicable to the databases with ACL security.

#variable_name1
This is the name of the variable that indicates the table for which the specified security values will be added for the specified user. A database_handle may precede the table name.

#variable_name2
This is the name of the variable that indicates the user id for which the specified table security values will be added.

#variable_name3
This is the name of the variable that indicates the integer value that represents the privileges to be added into the specified table. (for example; #acessvalue = %modify_access + %read_access)

#variable_name4
This is the name of the variable that indicates the grant option value to be added. This is an optional parameter. If present, its value (Y or N) will be added to the specified user, if applicable (only databases with ANSI security have this option). If not present, its default value is N. This is not applicable to the databases with ACL security.

DML Metadata Commands IAF 8.0 DML

10-39

ADD_TABLE_SECURITY

Example 1
Procedure_form main ! The following example adds a security entry for user jim ! with %read_access and no grant option to table members in ! videos database #ret = ADD_TABLE_SECURITY( "videos.members", jim, %read_access ) End_form

Example 2
Procedure_form main ! The following example adds a security entry for user jim ! with %read_access and %write_access with grant option Y to ! table members in videos database #db_table = "videos.members" #user = "jim" #access = %read_access + %write_access #grant_opt = "y" #ret = ADD_TABLE_SECURITY( #db_table, #user, #access, #grant_opt ) End_form

10-40

DML Metadata Commands IAF 8.0 DML

ADD TIME_TRIGGER

ADD TIME_TRIGGER
Syntax
ADD TIME_TRIGGER trigger_name [/qualifiers]

Description
This metadata command allows you to add a time trigger to the database. A time trigger executes DML code at a specified date and time. For information on defining time triggers via the Data Definition Editor, refer to the IAF System Reference Manual. For a topical discussion of time triggers and update triggers, refer to the IAF Users Guide.

Qualifiers
The following qualifiers are valid for use with the ADD TIME_TRIGGER metadata command:

/DATABASE=string_value
This qualifier allows you to specify any operating system commands that IAF is to execute prior to the trigger, and the databases associated with the time trigger. Specify this qualifier once for each operating system command that IAF is to execute and once for each database associated with the time trigger. IAF assumes that any /DATABASE qualifier specification beginning with a $ sign is an operating system command. When specifying a database via the /DATABASE qualifier, use the following format:
database_handle=database_file_specification

/DESCRIPTION=string_value /DML=(dml_statement)
This qualifier allows you to specify the DML code that IAF is to execute when the time trigger is activated.

DML Metadata Commands IAF 8.0 DML

10-41

ADD TIME_TRIGGER

/FINISH_DATE=string_value /LOG_FILE=string_value /QUEUE=string_value

Indicates the name of the batch queue in which the time trigger is to execute. The queue name is case sensitive. The Batch Service has a predefined queue - DEFAULT.

/REASON=string_expression
This qualifier allows you to specify a string expression indicating the reason for adding the time trigger. If the GEM_META_AUDIT_REASON System Customization Variable (SCV) is set to TRUE, the reason that this qualifier specifies is the default reason that IAF displays in the run--time window that facilitates entering the reason for the metadata change. If the GEM_META_AUDIT_REASON SCV is undefined or set to FALSE, the reason that this qualifier specifies is the reason that IAF stores in the given database. For details regarding the GEM_META_AUDIT_REASON SCV, refer to the IAF guide that applies to your operating system.

/RUN_DATES=string_value /START_DATE=string_value /USERNAME=username

This qualifier allows you specify the username under which to add and execute the time trigger. Note that you can specify a username only if you have adequate privileges to do so. If you do not specify a username, IAF adds and executes the trigger under the username associated with the current process.

Example
ADD TIME_TRIGGER WEEKLY_UPDATE & /DESCRIPTION=Weekly Job Update & /LOG_FILE=WEEKLY_UPDATE_LOG & /RUN_DATE=%%--%%%--%%%% 02:00:00.00 MON & /DML=PERFORM PROG:WEEKLY_JOB_UPDATE & /QUEUE=TRIGGER_QUEUE & /DATABASE=FIN=FINANCE & /DATABASE=MAN=MANUFACTURING

10-42

DML Metadata Commands IAF 8.0 DML

ADD VIEW

ADD VIEW
Syntax
ADD VIEW view_name [/qualifiers]

Description
This metadata command allows you to add a view. Views can be used to subset a table, or join the data from two or more tables to present a single consistent relation.

Qualifiers
The following qualifiers are valid for use with the ADD VIEW metadata command:

/ADD_FIELD=local_field_name BASED_ON table_name(field_name) [/field_detail_qualifiers]

or

/ADD_FIELD=local_field_name COMPUTED_BY (computed_expression) [/field_detail_qualifiers]

This qualifier allows you to specify a field for the view you are adding. Specify this qualifier once for each field that is to be in the view. The first format above specifies a field that is based on a global field. The second format specifies a computed field. You can use field detail qualifiers to specify the fields attributes. For information on field detail qualifiers, refer to this sections Field Detail Qualifiers heading. For details on global, based on, and computed fields, refer to the discussion of the Data Definition Editor in the IAF guide that applies to the database engine in use. You must specify a table via the /TABLE view source qualifier before using the table in an /ADD_FIELD qualifiers expression. For details on view source qualifiers, refer to this sections View Source Qualifiers heading.

DML Metadata Commands IAF 8.0 DML

10-43

ADD VIEW

/DESCRIPTION=string_value /REASON=string_expression
This qualifier allows you to specify a string expression indicating the reason for adding the view. If the GEM_META_AUDIT_REASON System Customization Variable (SCV) is set to TRUE, the reason that this qualifier specifies is the default reason that IAF displays in the run--time window that facilitates entering the reason for the metadata change. If the GEM_META_AUDIT_REASON SCV is undefined or set to FALSE, the reason that this qualifier specifies is the reason that IAF stores in the given database. For details regarding the GEM_META_AUDIT_REASON SCV, refer to the IAF guide that applies to your operating system.

/VIEW_SOURCE=(/view_source_qualifiers)
This qualifier allows you to specify the views source, including the table(s) from which to obtain the view data, and the selection criteria for the view data, among other things. For details on the view source qualifiers that enable you to make these specifications, refer to this sections View Source Qualifiers heading.

Field Detail Qualifiers

You can include the following field detail qualifiers after each / ADD_FIELD qualifier to specify the given fields details (i.e. attributes):

/DESCRIPTION=string_value /HEADING=string_value /HELP=string_value

This qualifier allows you to specify a line of help text for the field. You may specify this qualifier as many times as needed to specify the desired help text message.

/INPUT_MASK=string_value
This qualifier allows you to specify the input mask to use for the field. For details regarding input masks, refer to this manuals INPUT AND OUTPUT masks appendix.

10-44

DML Metadata Commands IAF 8.0 DML

ADD VIEW

/OUTPUT_MASK=string_value
This qualifier allows you to specify the output mask to use for the field. For details regarding output masks, refer to this manuals INPUT AND OUTPUT masks appendix.

/PROMPT=string_value

View Source Qualifiers

You can specify the following view source qualifiers via the /VIEW_SOURCE qualifier (see the Qualifiers heading on the preceding page):

/FIRST=numeric_value /REDUCED_TO=field_name[,field_name[,...]] /TABLE=table_name[,table_name[,...]] /SELECTION=(quoted_selection_expression) /SORTED_BY=field_name[,field_name[,...]] Note:

The /SORTED_BY qualifier is not implemented for any database engine except Rdb.

DML Metadata Commands IAF 8.0 DML

10-45

ADD VIEW

/WITH=field_name operator value

or

/WITH=field_name operator context.field_name

These qualifiers are very similar to those that apply to the DML START_STREAM statement. For details regarding these qualifiers, refer to the description of the START_STREAM statement in this manuals LANGUAGE STATEMENTS chapter.

Example
ADD VIEW ORDER_DETAILS & /DESCRIPTION=Orders View & /VIEW_SOURCE=(/TABLE=ORDERS,ORDER_LINES & /SORTED_BY=ORDER_NUMBER & /WITH=DEPARTMENT<>HD) & /ADD_FIELD=ORDER_NUMBER BASED_ON ORDER(ORDER_NUMBER) & /ADD_FIELD=LINE_NUMBER BASED_ON ORDER_LINES(LINE_NUMBER) & /ADD_FIELD=PART_NUMBER BASED ON ORDER_LINES(PART_NUMBER) & /ADD_FIELD=LINE_VALUE COMPUTED_BY & (ORDER_LINES(UNIT_COST)*ORDER_LINES(QUANTITY)) & /DESCRIPTION=Line Value & /PROMPT=Line Value & /HEADING=Line,Value & /OUTPUT_MASK=!--@@@@@@0.0@

10-46

DML Metadata Commands IAF 8.0 DML

CONVERT DATABASE

CONVERT DATABASE
Syntax
CONVERT DATABASE invoke-path TO UNICODE /ENGINE=MSSQL CONVERT DATABASE invoke-path to VARCHAR2 /ENGINE=ORACLE

Description
Command converts a database to a destination of Unicode or VARCHAR2.

Qualifiers
UNICODE
IAF provides a mechanism to convert a non-Unicode database to a Unicode database. Note that the conversion process is irreversible. Once your database has been converted, it cannot be converted back. Please ensure that you have a good backup of your database before proceeding. The database must have first been upgraded to the latest IAF metadata level with INVOKE /UPGRADE before it may be converted. GEM_DATABASE(GEM_PATCH_LEVEL) should be 16 or higher. The converter checks for this patch level both before the interactive dialog is reached and also from within the converter proper. The conversion also requires exclusive access to the database. The database must not be invoked. If it is currently invoked, please use the FINISH command to close it. Note that IAF is NOT able to determine if other users, including the IAF monitor, are accessing the database. Please stop the IAF monitor service and ensure that no other users, be they local or remote, are accessing the database. The non-Unicode to Unicode database converter is a DML command that can be performed either from the GEM> prompt or from within a DML program:

GEM>

CONVERT DATABASE "invoke-path" TO UNICODE /ENGINE=MSSQL

DML Metadata Commands IAF 8.0 DML

10-47

CONVERT DATABASE

Where invoke-path is the same invoke path that you would enter if you invoked the database with the INVOKE command. The CONVERT DATABASE statement brings up an interactive dialog that contains a warning followed by several prompts. The first prompt permits you to enter a conversion log file specification. The following prompts are to confirm that you have a good backup of your database, that you have exclusive access to the database, and that you are ready to proceed. The conversion begins immediately after you answer these questions. Please always check the conversion log file after the conversion completes, regardless of success or failure of the conversion process. When using Unicode databases, your GEM_CHARACTER_SET SCV setting is very important. It must be correct otherwise data conversion errors may occur. The default setting is ISO-8859-1. The SCV GEM_DB_CHARSET is not used for invoked Unicode databases, but is still used for all invoked non-Unicode and non-MSSQL engine databases. The non-Unicode to Unicode database converter defaults the nonUnicode database collation using the GEM_CHARACTER_SET SCV as follows:

GEM_CHARACTER _SET EUC-CN EUC-TW EUC-KR EUC-JP ISO-8859-1 CP437 CP850 CP1250

Collation Chinese_PRC_CS_AS Chinese_Taiwan_Stroke_CS_AS Korean_Wonsung_BIN Japanese_CS_AS SQL_Latin1_general_CP1_CS_AS SQL_Latin1_General_Cp437_CS_AS SQL_Latin1_General_Cp850_CS_AS SQL_Latin1_General_Cp1250_CS_AS

Comment Simplified Chinese Traditional Chinese Korean Japanese Western Europe United States (ISO 8879:1886) Multilingual (ISO 8879:1986) Albanian, Croatian, Czech, Hungarian, Polish, Romanian,Slovak, Slovenia

10-48

DML Metadata Commands IAF 8.0 DML

CONVERT DATABASE

GEM_CHARACTER _SET CP1251 CP1253 CP1254 CP1255 CP1256 CP1257

Collation SQL_Latin1_General_Cp1251_CS_AS SQL_Latin1_General_Cp1253_CS_AS SQL_Latin1_General_Cp1254_CS_AS SQL_Latin1_General_Cp1255_CS_AS SQL_Latin1_General_Cp1256_CS_AS SQL_Latin1_General_Cp1257_CS_AS

Comment Cyrillic, Macedonian, Ukrainian Greek Turkish Hebrew Arabic Latvian, Lithuanian

Unicode databases use SQLserver data type NVARCHAR for both TEXT and VARYING_STRING IAF data types.

VARCHAR2
IAF provides a mechanism to convert existing CHAR columns in Oracle databases to VARCHAR2 columns. Note that the conversion process is irreversible. Once your database has been converted, it cannot be converted back. Please ensure that you have a good backup of your database before proceeding. The database must have first been upgraded the IAF V7.2.0 metadata level with INVOKE /UPGRADE before it may be converted. GEM_DATABASE(GEM_PATCH_LEVEL) should be 52 or higher. The converter checks for this patch level both before the interactive dialog is reached and also from within the converter proper. The conversion also requires exclusive access to the database. The database must not be invoked. If it is currently invoked, please use the FINISH command to close it. Note that IAF is NOT able to determine if other users, including the monitor process, daemon or service, are accessing the database. Please stop monitor and ensure that no other users, be they local or remote, are accessing the database. The CHAR to VARCHAR2 database converter is a DML command that can be performed either from the DML> prompt or from within a DML program:
DML> CONVERT DATABASE invoke-path TO VARCHAR2 /ENGINE=ORACLE

Where invoke-path is the same invoke path that you would enter if you invoked the database with the INVOKE command. The optional /VERBOSE qualifier may also be specified.

DML Metadata Commands IAF 8.0 DML

10-49

CONVERT DATABASE

The CONVERT DATABASE statement brings up an interactive dialog that contains a warning followed by several prompts. The first prompt permits you to enter a conversion log file specification. The following prompts are to confirm that you have a good backup of your database, that you have exclusive access to the database, and that you are ready to proceed. The conversion begins immediately after you answer these questions. Please always check the conversion log file after the conversion completes, regardless of success or failure of the conversion process. The following points should be taken in count prior to attempting this conversion: A full cold backup should be performed prior to the conversion The database shouldnt be in archive log mode during the conversion Enough rollback segment/undo space should be available, at least as much as your largest table.

10-50

DML Metadata Commands IAF 8.0 DML

DELETE CLASS

DELETE CLASS
Syntax
DELETE CLASS class_name [/qualifier]

Description
This metadata command allows you to delete a class. For information regarding classes, refer to the discussion of the System Definition Editor in the IAF System Reference Manual.

Qualifier
The following qualifier is valid for use with the DELETE CLASS metadata command:
/REASON=string_expression

This qualifier allows you to specify a string expression indicating the reason for deleting the class. If the GEM_META_AUDIT_REASON System Customization Variable (SCV) is set to TRUE, the reason that this qualifier specifies is the default reason that IAF displays in the run--time window that facilitates entering the reason for the metadata change. If the GEM_META_AUDIT_REASON SCV is undefined or set to FALSE, the reason that this qualifier specifies is the reason that IAF stores in the given database. For details regarding the GEM_META_AUDIT_REASON SCV, refer to the IAF guide that applies to your operating system.

Example
DELETE CLASS REPORTS

DML Metadata Commands IAF 8.0 DML

10-51

DELETE DATATYPE

DELETE DATATYPE
Syntax
DELETE DATATYPE datatype_name [/qualifier]

Description
This metadata command allows you to delete a datatype. If the given datatype is specified for a field, IAF asks whether the characteristics of the datatype are to be transferred to the field. For information regarding datatypes, refer to the IAF guide that applies to the database engine in use.

Qualifier
The following qualifier is valid for use with the DELETE DATATYPE metadata command:

/REASON=string_expression
This qualifier allows you to specify a string expression indicating the reason for deleting the datatype. If the GEM_META_AUDIT_REASON System Customization Variable (SCV) is set to TRUE, the reason that this qualifier specifies is the default reason that IAF displays in the run--time window that facilitates entering the reason for the metadata change. If the GEM_META_AUDIT_REASON SCV is undefined or set to FALSE, the reason that this qualifier specifies is the reason that IAF stores in the given database. For details regarding the GEM_META_AUDIT_REASON SCV, refer to the IAF guide that applies to your operating system.

Example
DELETE DATATYPE PERCENTAGE

10-52

DML Metadata Commands IAF 8.0 DML

DELETE DOMAIN

DELETE DOMAIN
Syntax
DELETE DOMAIN domain_name [/qualifier]

Description
This metadata command allows you to delete an explicit domain. For information on defining domains via the Data Definition Editor, refer to the IAF System Reference Manual. For an in--depth discussion of domains, refer to the IAF Users Guide.

NOTE:
To disable implicit domains in the current database, append the / NOIMPLICIT qualifier to the INVOKE statement or the GEM_DATABASE_n System Customization Variable (SCV) at start--up time. For details regarding the INVOKE statement and its qualifiers, refer to this manuals LANGUAGE STATEMENTS chapter. For details regarding the GEM_DATABASE_n SCV, refer to the IAF guide that applies to your operating system.

Qualifier
The following qualifier is valid for use with the DELETE DOMAIN metadata command:

/REASON=string_expression
This qualifier allows you to specify a string expression indicating the reason for deleting the explicit domain. If the GEM_META_AUDIT_REASON SCV is set to TRUE, the reason that this qualifier specifies is the default reason that IAF displays in the run-time window that facilitates entering the reason for the metadata change. If the GEM_META_AUDIT_REASON SCV is undefined or set to FALSE, the reason that this qualifier specifies is the reason that IAF stores in the given database. For details regarding the GEM_META_AUDIT_REASON SCV, refer to the IAF guide that applies to your operating system.

Example
DELETE DOMAIN ORDERS_ORDER_LINES

DML Metadata Commands IAF 8.0 DML

10-53

DELETE EVENT

DELETE EVENT
Syntax
DELETE EVENT event_name

Description
Deletes an event record to the GEM_METADATA_AUDIT table. The event name is a required parameter. An unquoted string literal, a quoted string literal or a variable is accepted. Expressions are not accepted. The event name is limited to 65 characters in length.

Example
DELETE EVENT PRE_616_UPGRADE DELETE EVENT #event

10-54

DML Metadata Commands IAF 8.0 DML

DELETE FACILITY

DELETE FACILITY
Syntax
DELETE FACILITY system_name:facility_name [/qualifier]

Description
This metadata command allows you to delete a facility. For information regarding facilities, refer to the discussion of the System Definition Editor in the IAF System Reference Manual.

Qualifier
The following qualifier is valid for use with the DELETE FACILITY metadata command:

/REASON=string_expression
This qualifier allows you to specify a string expression indicating the reason for deleting the facility. If the GEM_META_AUDIT_REASON System Customization Variable (SCV) is set to TRUE, the reason that this qualifier specifies is the default reason that IAF displays in the run--time window that facilitates entering the reason for the metadata change. If the GEM_META_AUDIT_REASON SCV is undefined or set to FALSE, the reason that this qualifier specifies is the reason that IAF stores in the given database. For details regarding the GEM_META_AUDIT_REASON SCV, refer to the IAF guide that applies to your operating system.

Example
DELETE FACILITY AC:INVOICING

DML Metadata Commands IAF 8.0 DML

10-55

DELETE_FACILITY_SECURITY

DELETE_FACILITY_SECURITY
Syntax
DELETE_FACILITY_SECURITY([database_handle.]system_name:facility _name, userid)

or
DELETE_FACILITY _SECURITY(#variable_name1, #variable_name2)

Category
Data access

Description
This function deletes the requested facility security. If the function is successful, it returns %NORMAL. Otherwise, it returns an error number whose components the ERROR_TEXT function can return.

db_handle
This is the handle for the database in which the given facility resides. It is necessary to specify a database handle only if you have invoked more than one database, and the specified system and facility do not reside in the current default database.

system_name
This is the name of the system that includes the given facility. For details on defining systems, refer to the discussion of the System Definition Editor in the IAF System Reference Manual.

facility_name
This is the name of the facility from which security will be deleted for the specified user. For details on defining facilities, refer to the discussion of the System Definition Editor in the IAF System Reference Manual.

userid
This is the user id for which facility security will be deleted.

#variable_name1
This is the name of the variable that indicates the system that includes the given facility. It is followed by the name of the facility for which security

10-56

DML Metadata Commands IAF 8.0 DML

DELETE_FACILITY_SECURITY

will be deleted. A database_handle may precede the system name. For details on defining systems and facilities, refer to the discussion of the System Definition Editor in the IAF System Reference Manual.

#variable_name2
This is the name of the variable that indicates the user id for which facility security will be deleted.

Example 1
Procedure_form main ! The following example deletes security entry of user jim ! from system sys1 and facility f1 in videos database #ret = DELETE_FACILITY_SECURITY( videos.sys1:f1, jim ) End_form

Example 2
Procedure_form main ! The following example deletes security entry of user jim ! from system sys1 and facility f1 in videos database #db_fac = "videos.sys1:f1" #user = "jim" #ret = DELETE_FACILITY_SECURITY( #db_fac, #user )End_form

DML Metadata Commands IAF 8.0 DML

10-57

DELETE FIELD

DELETE FIELD
Syntax
DELETE FIELD field_name [/qualifier]

Description
This metadata command allows you to delete a global field. You cannot delete a global field that a table references. You must first delete the field from the table, then delete the field. For information on deleting a global field from a table, refer to this chapters description of the MODIFY TABLE metadata command.

Qualifier
The following qualifier is valid for use with the DELETE FIELD metadata command:

/REASON=string_expression
This qualifier allows you to specify a string expression indicating the reason for deleting the field. If the GEM_META_AUDIT_REASON System Customization Variable (SCV) is set to TRUE, the reason that this qualifier specifies is the default reason that IAF displays in the run--time window that facilitates entering the reason for the metadata change. If the GEM_META_AUDIT_REASON SCV is undefined or set to FALSE, the reason that this qualifier specifies is the reason that IAF stores in the given database. For details regarding the GEM_META_AUDIT_REASON SCV, refer to the IAF guide that applies to your operating system.

Example
DELETE FIELD SALESMAN

10-58

DML Metadata Commands IAF 8.0 DML

DELETE INDEX

DELETE INDEX
Syntax
DELETE INDEX index_name [/qualifier]

Description
This metadata command allows you to delete an index. For information regarding indices, refer to the IAF guide that applies to the database engine in use.

Qualifier
The following qualifier is valid for use with the DELETE INDEX metadata command:

/REASON=string_expression
This qualifier allows you to specify a string expression indicating the reason for deleting the index. If the GEM_META_AUDIT_REASON System Customization Variable (SCV) is set to TRUE, the reason that this qualifier specifies is the default reason that IAF displays in the run--time window that facilitates entering the reason for the metadata change. If the GEM_META_AUDIT_REASON SCV is undefined or set to FALSE, the reason that this qualifier specifies is the reason that IAF stores in the given database. For details regarding the GEM_META_AUDIT_REASON SCV, refer to the IAF guide that applies to your operating system.

Example
DELETE INDEX CUSTOMERS

DML Metadata Commands IAF 8.0 DML

10-59

DELETE MANAGER_ROLE

DELETE MANAGER_ROLE
Syntax
DELETE MANAGER_ROLE[user_name:role_name1,role_name2, etc...]

Category
Program flow

Description
This command deletes entry(ies) from table GEM_ROLE_USERS with identification M in GEM_USER_TYPE column, which means that user_name will no longer be part of the role(s) just deleted.

Example
DELETE MANAGER_ROLE dinats:DEV,USERS

Deletes roles DEV, USERS from dinats as Manager of the roles.

10-60

DML Metadata Commands IAF 8.0 DML

DELETE MESSAGE

DELETE MESSAGE
Syntax
DELETE MESSAGE message_name [/qualifier]

Description
This metadata command allows you to delete an application message. For information regarding messages, refer to the discussion of the Data Definition Editor in the IAF System Reference Manual, and the description of the MESSAGE statement in this manuals LANGUAGE STATEMENTS chapter.

Qualifier
The following qualifier is valid for use with the DELETE MESSAGE metadata command:

/REASON=string_expression
This qualifier allows you to specify a string expression indicating the reason for deleting the message. If the GEM_META_AUDIT_REASON System Customization Variable (SCV) is set to TRUE, the reason that this qualifier specifies is the default reason that displays in the run--time window that facilitates entering the reason for the metadata change. If the GEM_META_AUDIT_REASON SCV is undefined or set to FALSE, the reason that this qualifier specifies is the reason that IAF stores in the given database. For details regarding the GEM_META_AUDIT_REASON SCV, refer to the IAF guide that applies to your operating system.

Example
DELETE MESSAGE INVALID_ID

DML Metadata Commands IAF 8.0 DML

10-61

DELETE PARAMETER

DELETE PARAMETER
Syntax
DELETE PARAMETER parameter_name [/qualifier]

Description
This metadata command allows you to delete the given parameter. For information regarding parameters, refer to the discussion of the Data Definition Editor in the IAF System Reference Manual.

Qualifier
The following qualifier is valid for use with the DELETE PARAMETER metadata command:

/REASON=string_expression
This qualifier allows you to specify a string expression indicating the reason for deleting the parameter. If the GEM_META_AUDIT_REASON System Customization Variable (SCV) is set to TRUE, the reason that this qualifier specifies is the default reason that displays in the run--time window that facilitates entering the reason for the metadata change. If the GEM_META_AUDIT_REASON SCV is undefined or set to FALSE, the reason that this qualifier specifies is the reason that IAF stores in the given database. For details regarding the GEM_META_AUDIT_REASON SCV, refer to the IAF guide that applies to your operating system.

Example
DELETE PARAMETER COMPANY_NAME

10-62

DML Metadata Commands IAF 8.0 DML

DELETE PROCEDURE

DELETE PROCEDURE
Syntax
DELETE PROCEDURE procedure_name [/qualifier]

Description
This metadata command allows you to delete a stored procedure. For information on stored procedures, refer to the IAF Users Guide and the discussion of the Data Definition Editor in the IAF System Reference Manual.

Qualifier
The following qualifier is valid for use with the DELETE PROCEDURE metadata command:

/REASON=string_expression
This qualifier allows you to specify a string expression indicating the reason for deleting the stored procedure. If the GEM_META_AUDIT_REASON System Customization Variable (SCV) is set to TRUE, the reason that this qualifier specifies is the default reason that displays in the run--time window that facilitates entering the reason for the metadata change. If the GEM_META_AUDIT_REASON SCV is undefined or set to FALSE, the reason that this qualifier specifies is the reason that IAF stores in the given database. For details regarding the GEM_META_AUDIT_REASON SCV, refer to the IAF guide that applies to your operating system.

Example
DELETE PROCEDURE CUSTOMER_LOOKUP

DML Metadata Commands IAF 8.0 DML

10-63

DELETE ROLE_MANAGER

DELETE ROLE_MANAGER
Syntax
DELETE ROLE_MANAGER[role_name:user_name1,user_name2, etc...]

Category
Program flow

Description
This command deletes entry(ies) from table GEM_ROLE_USERS with identification M in GEM_USER_TYPE column, which means that user(s) will no longer be part of the role_name just deleted.

Example
DELETE ROLE_MANAGER DEV:dinats,lisa

Deletes users dinats, lisa from role DEV as Managers of the role.

10-64

DML Metadata Commands IAF 8.0 DML

DELETE TABLE

DELETE TABLE
Syntax
DELETE TABLE table_name [/qualifier]

Description
This metadata command allows you to delete a real or virtual table from the current database. You cannot delete a table that a view references. You must first modify the view, then delete the table. For information regarding virtual tables, refer to the IAF Users Guide.

Qualifier
The following qualifier is valid for use with the DELETE TABLE metadata command:

/REASON=string_expression
This qualifier allows you to specify a string expression indicating the reason for deleting the table. If the GEM_META_AUDIT_REASON System Customization Variable (SCV) is set to TRUE, the reason that this qualifier specifies is the default reason that IAF displays in the run--time window that facilitates entering the reason for the metadata change. If the GEM_META_AUDIT_REASON SCV is undefined or set to FALSE, the reason that this qualifier specifies is the reason that IAF stores in the given database. For details regarding the GEM_META_AUDIT_REASON SCV, refer to the IAF guide that applies to your operating system.

Example
DELETE TABLE CUSTOMERS

DML Metadata Commands IAF 8.0 DML

10-65

DELETE_TABLE_SECURITY

DELETE_TABLE_SECURITY
Syntax
DELETE_TABLE_SECURITY DELETE_TABLE_SECURITY ([database_handle.]table_name, userid)

or
DELETE_TABLE_SECURITY (#variable_name1, #variable_name2)

Category
Data access

Description
This function deletes the requested table security. If the function is successful, it returns %NORMAL. Otherwise, it returns an error number whose components the ERROR_TEXT function can return.

db_handle
This is the handle for the database in which the given table resides. It is necessary to specify a database handle only if you have invoked more than one database, and the specified table does not reside in the current default database. If the database_handle is indicated, the database_handle and the table_name have to be enclosed in quotes (see examples below.)

table_name
This is the name of the table for which security will be deleted.

userid
This is the user id for which table security will be deleted.

#variable_name1
This is the name of the variable that indicates the table for which security will be deleted. A database_handle may precede the table name.

10-66

DML Metadata Commands IAF 8.0 DML

DELETE_TABLE_SECURITY

#variable_name2
This is the name of the variable that indicates the user id for which table security will be deleted.

Example 1
Procedure_form main ! The following example deletes security entry of user jim ! from table members in videos database #ret = DELETE_TABLE_SECURITY( "videos.members", jim ) End_form

Example 2
Procedure_form main ! The following example deletes security entry of user jim ! from table members in videos database #db_table = "videos.members" #user = "jim" #ret = DELETE_TABLE_SECURITY( #db_table, #user ) End_form

DML Metadata Commands IAF 8.0 DML

10-67

DELETE TIME_TRIGGER

DELETE TIME_TRIGGER
Syntax
DELETE TIME_TRIGGER trigger_name [/qualifiers]

Description
This metadata command allows you to delete a time trigger. For information regarding time triggers, refer to the discussion of the Data Definition Editor in the IAF System Reference Manual.

Qualifiers
The following qualifiers are valid for use with the DELETE TIME_TRIGGER metadata command:

/REASON=string_expression
This qualifier allows you to specify a string expression indicating the reason for deleting the time trigger. If the GEM_META_AUDIT_REASON System Customization Variable (SCV) is set to TRUE, the reason that this qualifier specifies is the default reason that IAF displays in the run--time window that facilitates entering the reason for the metadata change. If the GEM_META_AUDIT_REASON SCV is undefined or set to FALSE, the reason that this qualifier specifies is the reason that IAF stores in the given database. For details regarding the GEM_META_AUDIT_REASON SCV, refer to the IAF guide that applies to your operating system.

/USERNAME=username Examples
DELETE TIME_TRIGGER MONTH_REPORT DELETE TIME_TRIGGER WEEKLY_UPDATE/USERNAME=SYSTEM

10-68

DML Metadata Commands IAF 8.0 DML

DELETE VIEW

DELETE VIEW
Syntax
DELETE VIEW view_name [/qualifier]

Description
This metadata command allows you to delete a view. For information regarding views, refer to the IAF guide that applies to the database engine in use.

Qualifier
The following qualifier is valid for use with the DELETE VIEW metadata command:

/REASON=string_expression
This qualifier allows you to specify a string expression indicating the reason for deleting the view. If the GEM_META_AUDIT_REASON System Customization Variable (SCV) is set to TRUE, the reason that this qualifier specifies is the default reason that IAF displays in the run--time window that facilitates entering the reason for the metadata change. If the GEM_META_AUDIT_REASON SCV is undefined or set to FALSE, the reason that this qualifier specifies is the reason that IAF stores in the given database. For details regarding the GEM_META_AUDIT_REASON SCV, refer to the IAF guide that applies to your operating system.

Example
DELETE VIEW ORDER_DETAILS

DML Metadata Commands IAF 8.0 DML

10-69

END_METADATA_BATCH

END_METADATA_BATCH
Syntax
END_METADATA_BATCH [/HANDLE=<db_handle>]

Description
This command triggers the execution of the DML metadata commands currently accrued in the batch which was started by the START_METADATA_BATCH command. If the command is successful, it returns %NORMAL. Otherwise, it returns a fatal error. IAF does not implement metadata batching on all engines. If this command is issued against an engine that does not support it, no error will be generated and the command will be ignored.

Qualifiers
The following qualifier is valid for use with the END_METADATA_BATCH metadata command:

/HANDLE
This qualifier specifies the database to which the metadata batching is to be applied. If no /HANDLE is specified, then the current database is assumed.

Additional information
Batched metadata changes are accumulated in an internal IAF table. When the END_METADATA_BATCH is received, the pending entries in this table are retrieved in groups according to their metadata types and objects, so that each metadata object can be updated in an efficient manner. If a failure occurs during the metadata update such that not all the modifications have finished (e.g. system parameters are set too low) the database is in an inconsistent state until the batch update is completed. See the INVOKE command for information about completing the batch update.

10-70

DML Metadata Commands IAF 8.0 DML

GET_FACILITY_SECURITY

GET_FACILITY_SECURITY
Syntax
GET_FACILITY_SECURITY ([database_handle.]system_name:facility_name, userid)

or
GET_FACILITY _SECURITY (#variable_name1, #variable_name2)

Category
Data access

Description
When this function is called with a specified userid, it returns the userid and access values in a formatted string for the facility_name and userid requested. When this function is called without userid (a null string), for every call it returns the next userid and access values for the specified table. When no security information exists for the facility_name requested, or once all the information has been returned, the function returns a null string ("").

db_handle
This is the handle for the database in which the given facility resides. It isnecessary to specify a database handle only if you have invoked more than one database, and the specified system and facility do not reside in the current default database.

system_name
This is the name of the system that includes the given facility. For details on defining systems, refer to the discussion of the System Definition Editor in the IAF System Reference Manual.

facility_name
This is the name of the facility for which to get the security values. For details on defining facilities, refer to the discussion of the System Definition Editor in the IAF System Reference Manual.

DML Metadata Commands IAF 8.0 DML

10-71

GET_FACILITY_SECURITY

userid
This is the user id for which facility security information is requested, or a null string to return all users and their access values one at a time.

#variable_name1
This is the name of the variable that indicates the system that includes the given facility. It is followed by the name of the facility for which to get the security values. For details on defining systems and facilities, refer to the discussion of the System Definition Editor in the IAF System Reference Manual.

#variable_name2
This is the name of the variable that indicates the user id for which facility security information is requested, or a null string to return all users and their access values one at a time.

Example 1
Procedure_form main ! The following example returns in #ret the access values of ! user jim for system sys1, facility f1, in videos database #ret = GET_FACILITY_SECURITY ( videos.sys1:f1, jim ) ! The following example returns in #ret the access values of ! all users, one at a time, for system sys1, facility f1, in ! videos database #ret = "begin_while" while ( #ret <> "" ) #ret = GET_FACILITY_SECURITY ( videos.sys1:f1, "" ) end_while End_form

10-72

DML Metadata Commands IAF 8.0 DML

GET_FACILITY_SECURITY

Example 2
Procedure_form main ! The following example returns in #ret the access values of ! user jim for system sys1, facility f1, in videos database #db_fac = "videos.sys1:f1" #user = "jim" #ret = GET_FACILITY_SECURITY( #db_fac, #user )

! The following example returns in #ret the access values of ! all users, one at a time, for system sys1, facility f1, in ! videos database #db_fac = "videos.sys1:f1" #user = "" #ret = "begin_while" while ( #ret <> "" ) #ret = GET_FACILITY_SECURITY ( #db_fac, #user ) end_while End_form

DML Metadata Commands IAF 8.0 DML

10-73

MODIFY CLASS

MODIFY CLASS
Syntax
MODIFY CLASS class_name [/qualifiers]

Description
This metadata command allows you to modify a class. For information regarding classes, refer to the discussion of the System Definition Editor in the IAF System Reference Manual.

Qualifiers
The following qualifiers are valid for use with the MODIFY CLASS metadata command:

/DESCRIPTION=string_value /REASON=string_expression
This qualifier allows you to specify a string expression indicating the reason for modifying the class. If the GEM_META_AUDIT_REASON System Customization Variable (SCV) is set to TRUE, the reason that this qualifier specifies is the default reason that IAF displays in the run--time window that facilitates entering the reason for the metadata change. If the GEM_META_AUDIT_REASON SCV is undefined or set to FALSE, the reason that this qualifier specifies is the reason that IAF stores in the given database. For details regarding the GEM_META_AUDIT_REASON SCV, refer to the IAF guide that applies to your operating system.

Example
MODIFY CLASS REPORTS & /DESCRIPTION=YEAR_END_REPORTS

10-74

DML Metadata Commands IAF 8.0 DML

MODIFY DATATYPE

MODIFY DATATYPE
Syntax
MODIFY DATATYPE datatype_name [/qualifiers]

Description
This metadata command allows you to modify a datatype. For details regarding datatypes, refer to the IAF guide that applies to the database engine in use.

Qualifiers
The following qualifiers are valid for use with the MODIFY DATATYPE metadata command:

/INPUT_MASK=string_value
This qualifier allows you to specify the input mask to use for the datatype. For details regarding input masks, refer to this manuals INPUT AND OUTPUT masks appendix.

/LENGTH=numeric_value /OUTPUT_MASK=string_value
This qualifier allows you to specify the output mask to use for the datatype. For details regarding output masks, refer to this manuals INPUT AND OUTPUT masks appendix.

/SCALE=numeric_value

DML Metadata Commands IAF 8.0 DML

10-75

MODIFY DATATYPE

/NATIVE=native_datatype
This qualifier allows you to specify the native datatype associated with the datatype you are modifying. Following is a list of valid native datatypes:
BYTE, UBYTENLO D_FLOATNR DATE_TIMENRO DDMMYYNU DDMMYYYYNUMTEXT DOCUMENTARYNZ F_FLOATPACKED G_FLOATQUADWORD H_FLOATTEXT LONGWORD, ULONGWORDVARYING_STRING MMDDYYWORD, UWORD MMDDYYYYYYMMDD NL YYYYMMDD

Note that not all datatypes are valid for all database engines. For details regarding datatypes that are valid for a particular database engine with which IAF operates, refer to the IAF guide that applies to that database engine.

/REASON=string_expression
This qualifier allows you to specify a string expression indicating the reason for modifying the datatype. If the GEM_META_AUDIT_REASON System Customization Variable (SCV) is set to TRUE, the reason that this qualifier specifies is the default reason that IAF displays in the run--time window that facilitates entering the reason for the metadata change. If the GEM_META_AUDIT_REASON SCV is undefined or set to FALSE, the reason that this qualifier specifies is the reason that IAF stores in the given database. For details regarding the GEM_META_AUDIT_REASON SCV, refer to the IAF guide that applies to your operating system.

10-76

DML Metadata Commands IAF 8.0 DML

MODIFY DATATYPE

/USER_ARGUMENT=string_value /VALID_VALUES=string_value Example

MODIFY DATATYPE MONEY & /NATIVE=LONGWORD

DML Metadata Commands IAF 8.0 DML

10-77

MODIFY FACILITY

MODIFY FACILITY
Syntax
MODIFY FACILITY system_name:facility_name [/qualifiers]

Description
This metadata command allows you to modify a facility. For details regarding facilities, refer to the discussion of the System Definition Editor in the IAF System Reference Manual.

Qualifiers
The following qualifiers are valid for use with the MODIFY FACILITY metadata command:

/ADD_CHILD=system_name:facility_name
This qualifier allows you to specify a facility that is to be the child of the facility you are modifying, and facilitates the maintenance of menu hierarchies.

/CLASS=class_name /DELETE_ALL_LINKS /DELETE_CHILD=system_name:facility_name

This qualifier allows you to delete a facility that is a child of the facility you are modifying, and facilitates the maintenance of menu hierarchies.

/DESCRIPTION=string_value /DML=(dml_statement) /HELP=string_value

This qualifier allows you to specify a line of help text for the facility. You may specify this qualifier as many times as needed to specify the desired help text message.

10-78

DML Metadata Commands IAF 8.0 DML

MODIFY FACILITY

/MENU_FORM=string_value /MENU_FILE=string_value /REASON=string_expression

This qualifier allows you to specify a string expression indicating the reason for modifying the facility. If the GEM_META_AUDIT_REASON System Customization Variable (SCV) is set to TRUE, the reason that this qualifier specifies is the default reason that IAF displays in the run--time window that facilitates entering the reason for the metadata change. If the GEM_META_AUDIT_REASON SCV is undefined or set to FALSE, the reason that this qualifier specifies is the reason that IAF stores in the given database. For details regarding the GEM_META_AUDIT_REASON SCV, refer to the IAF guide that applies to your operating system.

/TAG_NAME=string_value Examples
MODIFY FACILITY AC:INVOICING & /TAG_NAME=IN MODIFY FACILITY AC:MASTER & /ADD_CHILD=AC:INVOICING & /ADD_CHILD=AC:RECEIVING

DML Metadata Commands IAF 8.0 DML

10-79

MODIFY FIELD

MODIFY FIELD
Syntax
MODIFY FIELD field_name [/qualifiers]

Description
This metadata command allows you to modify a fields definition.

Qualifiers
The following qualifiers are valid for use with the MODIFY FIELD metadata command:

/DATATYPE=datatype
This qualifier allows you to specify the fields datatype. The /DATATYPE qualifier can specify a native datatype or a user--defined datatype. For details regarding native and user--defined datatypes for a particular IAF-supported database engine, refer to the IAF guide that applies to that database engine. Note that you cannot change the datatype of a DOCUMENTARY or SEGMENTED_STRING field.

/DESCRIPTION=string_value /DEFAULT=string_value /DOMAIN=string_value

See /DOMAIN on page 5-48.

/FLAGS=flag_value[,flag_value[,...]]
This qualifier allows you to specify one or more of the following flag values: NONE, LOWERCASE, REQUIRED, NUMERIC, ZEROFILL, FULL, POSITIVE, ALPHA, NOZERO. For details regarding these flag values, refer to the discussion of the Data Definition Editor in the IAF guide that applies to the database engine in use.

10-80

DML Metadata Commands IAF 8.0 DML

MODIFY FIELD

/HEADING=string_value /HELP=string_value /INITIAL_VALUE=string_expression

This qualifier allows you to specify the initial value for the field. The initial value can be a constant value or one of the special keywords that the following table lists and describes. Keyword %MISSING Description This keyword indicates that the fields initial value is to be the missing value. Note that not all database engines support missing values. To determine if a particular IAF--supported database engine supports missing values, refer to the IAF guide that applies to that database engine. This is the default initial value on database engines that support missing values. This keyword indicates that the fields initial value is to be zero for numeric fields or a null string () for non--numeric fields. This is the default initial value on database engines that do not support missing values. This keyword indicates that the fields initial value is to be the date and time at which the record in which the field resides was added, and should be used for fields of a DATE_TIME datatype. It can also be used on fields of a TEXT datatype (IAF stores the data in the format YYYYMMDDHHMMSSCC). This keyword indicates that the fields initial value is to be the username associated with the process that is adding the record in which the field resides, and should be used only for fields of a TEXT datatype.

%NOT_MISSING

%NOW

%USERNAME

Note that to IAF, the constructs /INITIAL_VALUE=%NOW and / INITIAL_VALUE=%NOW are equivalent (i.e. enclosing the keyword in quotes does not affect the definition of the initial value).

DML Metadata Commands IAF 8.0 DML

10-81

MODIFY FIELD

/INPUT_MASK=string_value
This qualifier allows you to specify the input mask to use for the field. For details regarding input masks, refer to this manuals INPUT AND OUTPUT masks appendix.

/LENGTH=numeric_value /MISSING=string_value /OUTPUT_MASK=string_value

This qualifier allows you to specify the output mask to use for the field. For details regarding output masks, refer to this manuals INPUT AND OUTPUT masks appendix.

/PROMPT=string_value /REASON=string_expression
This qualifier allows you to specify a string expression indicating the reason for modifying the field. If the GEM_META_AUDIT_REASON System Customization Variable (SCV) is set to TRUE, the reason that this qualifier specifies is the default reason that IAF displays in the run--time window that facilitates entering the reason for the metadata change. If the GEM_META_AUDIT_REASON SCV is undefined or set to FALSE, the reason that this qualifier specifies is the reason that IAF stores in the given database. For details regarding the GEM_META_AUDIT_REASON SCV, refer to the IAF guide that applies to your operating system.

/SCALE=numeric_value /SHORT_PROMPT=string_value /USER_ARGUMENT=string_value /VALIDATION=dml_string_value Example

MODIFY FIELD ORDER_NUMBER & /INPUT_MAST=!@@@--@@@ & /OUTPUT_MASK=!@@@--@@@

10-82

DML Metadata Commands IAF 8.0 DML

MODIFY MESSAGE

MODIFY MESSAGE
Syntax
MODIFY MESSAGE message_name [/qualifiers]

Description
This metadata command allows you to modify an application message. For information regarding messages, refer to the discussion of the Data Definition Editor in the IAF System Reference Manual.

Qualifiers
The following qualifiers are valid for use with the MODIFY MESSAGE metadata command:

/REASON=string_expression
This qualifier allows you to specify a string expression indicating the reason for modifying the message. If the GEM_META_AUDIT_REASON System Customization Variable (SCV) is set to TRUE, the reason that this qualifier specifies is the default reason that IAF displays in the run--time window that facilitates entering the reason for the metadata change. If the GEM_META_AUDIT_REASON SCV is undefined or set to FALSE, the reason that this qualifier specifies is the reason that IAF stores in the given database. For details regarding the GEM_META_AUDIT_REASON SCV, refer to the IAF guide that applies to your operating system.

/SEVERITY=severity_code
This qualifier allows you to specify a code indicating the severity of the message you are modifying. Valid severity codes for use with this qualifier are ERROR, FATAL, INFORMATIONAL, SUCCESS, and WARNING. If you do not explicitly specify a severity code for a given message, IAF uses ERROR as the default severity code.

/TEXT=string_value
This qualifier allows you to specify the text of the message you are modifying.

DML Metadata Commands IAF 8.0 DML

10-83

MODIFY MESSAGE

Example
MODIFY MESSAGE NO_DIV & /SEVERITY=INFORMATIONAL

10-84

DML Metadata Commands IAF 8.0 DML

MODIFY TABLE

MODIFY TABLE
Syntax
MODIFY TABLE table_name [/qualifiers]

Description
This metadata command allows you to modify a table.

Qualifiers
The following qualifiers are valid for use with the MODIFY TABLE metadata command:

/ADD_FIELD=global_field_name
or

/ADD_FIELD=local_field_name BASED_ON global_field_name [/field_detail_qualifiers]

or

/ADD_FIELD=local_field_name COMPUTED_BY (computed_expression) [/field_detail_qualifiers]

This qualifier allows you to specify a field to add to the table you are modifying. Specify this qualifier once for each field to add to the table. The first format above specifies a global field. The second format specifies a field that is based on a global field. The third format specifies a computed field. When specifying a based on or computed field, you may use field detail qualifiers to specify the fields attributes. For information on field detail qualifiers see the Field Detail Qualifiers heading on the following page. For details on global, based on, and computed fields, refer to the discussion of the Data Definition Editor in the IAF guide that applies to the database engine in use.

/ARCHIVE
Make the table archivable for use with Transaction Archiving (see Appendix H, IAF Transaction Archiving). This has the effect of adding a GEM_ARCHIVE_FLAG column to the table unless the table already has such a column, in which case this qualifier is ignored. The

DML Metadata Commands IAF 8.0 DML

10-85

MODIFY TABLE

default action when neither /ARCHIVE nor /NOARCHIVE is specified is to preserve the tables current archivable setting. The GEM_ARCHIVE_FLAG column is used by the MARK, UNMARK and ARCHIVE statements as well as the IS_MARKED() and IS_MARKED_ON_STREAM() functions.

/DELETE_FIELD=field_name
This qualifier allows you to specify the name of a field to delete from the table. Specify this qualifier once for each field to delete.

/DESCRIPTION=string_value /LOCATION=string_value
This qualifier allows you to specify a string indicating the name and location of the tables datafile. Note that this qualifier applies only to the RMS database engine.

/MODIFY_FIELD=field_name [/field_detail_qualifiers]
This qualifier allows you to modify the field details for a based on or computed field. For details regarding based on and computed fields, refer to the discussion of the Data Definition Editor in the IAF guide that applies to the database engine in use.

/NOARCHIVE
If the table is currently archivable, then remove any GEM_ARCHIVE_FLAG column and make the table non-archivable. This qualifier is ignored if the table is not currently archivable. The default action when neither /ARCHIVE nor /NOARCHIVE is specified is to preserve the tables current archivable setting.

/REASON=string_expression
This qualifier allows you to specify a string expression indicating the reason for modifying the table. If the GEM_META_AUDIT_REASON System Customization Variable (SCV) is set to TRUE, the reason that this qualifier specifies is the default reason that IAF displays in the run--time window that facilitates entering the reason for the metadata change. If the GEM_META_AUDIT_REASON SCV is undefined or set to FALSE, the reason that this qualifier specifies is the reason that IAF stores in the given database. For details regarding the GEM_META_AUDIT_REASON SCV, refer to the IAF guide that applies to your operating system.

10-86

DML Metadata Commands IAF 8.0 DML

MODIFY TABLE

/STATIC
This qualifier indicates that the table that MODIFY TABLE metadata command is modifying is a static table. In effect, a static table is a template for data in an existing datafile. Typically, the datafile is used by one or more applications external to IAF. Any changes to a static tables metadata (for example; field definitions) changes only the way IAF views the existing data (i.e. IAF makes no structural changes that would impact any non--IAF applications using the given data). Note that this qualifier applies only to the RMS database engine. For more information regarding static tables, refer to the Guide to Using IAF with RMS.

Field Detail Qualifiers

You can include the following field detail qualifiers after each / ADD_FIELD qualifier that specifies a based on or computed field, and after each /MODIFY_FIELD qualifier. These qualifiers enable you to specify the given fields details (i.e. attributes):

/DESCRIPTION=string_value /HEADING=string_value /HELP=string_value

This qualifier allows you to specify a line of help text for the field. You may specify this qualifier as many times as needed to specify the desired help text message.

/INPUT_MASK=string_value
This qualifier allows you to specify the input mask to use for the field. For details regarding input masks, refer to this manuals INPUT AND OUTPUT masks appendix.

/OUTPUT_MASK=string_value
This qualifier allows you to specify the output mask to use for the field. For details regarding output masks, refer to this manuals INPUT AND OUTPUT masks appendix.

/POSITION=numeric_value
This qualifier allows you to specify the given fields offset, based on a starting offset of zero (i.e. the tables first field has an offset of zero). Note that this qualifier applies only to static tables when using the RMS

DML Metadata Commands IAF 8.0 DML

10-87

MODIFY TABLE

database engine. For details regarding static table, refer to the Guide to Using IAF with RMS.

/PROMPT=string_value /SHORT_PROMPT=string_value Examples

MODIFY TABLE ORDER_LINES & /DELETE_FIELD=LINE_VALUE & /ADD_FIELD=SALESMAN & /ADD_FIELD=TOTAL_VALUE MODIFY TABLE ORDER_LINES & /ADD_FIELD=EXTENDED_VALUE COMPUTED_BY & (ORDER_LINES(QUANTITY) * ORDER_LINES(UNIT_COST)) & /DESCRIPTION=Extended Value & /HEADING=Extended Value & /PROMPT=Extended Value & /SHORT_PROMPT=Value & /OUTPUT_MASK=!--@@@,@@@.0@

10-88

DML Metadata Commands IAF 8.0 DML

MODIFY TABLE_FIELD

MODIFY TABLE_FIELD
Syntax
MODIFY TABLE_FIELD table_name(field_name) [/qualifiers]

Description
This metadata command allows you to modify a table field. This statement is useful for maintaining update triggers and data audit options on table fields. For information regarding update triggers and data auditing, refer to the IAF System Reference Manual.

Qualifiers
The following qualifiers are valid for use with the MODIFY TABLE_FIELD metadata command:

/ADD_TRIGGER=(dml_statement) /AUDIT=audit_option[,audit_option[,...]]
This qualifier allows you to specify audit options for the given table field. Valid audit options for use with this qualifier are ADD, DELETE, MODIFY, and NONE. The NONE option disables data auditing for the field. For details regarding data auditing, refer to the IAF System Reference Manual.

/DELETE_TRIGGER /MODIFY_TRIGGER=(dml_statement)

DML Metadata Commands IAF 8.0 DML

10-89

MODIFY TABLE_FIELD

/REASON=string_expression
This qualifier allows you to specify a string expression indicating the reason for modifying the table field. If the GEM_META_AUDIT_REASON System Customization Variable (SCV) is set to TRUE, the reason that this qualifier specifies is the default reason that IAF displays in the run--time window that facilitates entering the reason for the metadata change. If the GEM_META_AUDIT_REASON SCV is set to FALSE or is undefined, the reason that this qualifier specifies is the reason that IAF stores in the given database. For details regarding the GEM_META_AUDIT_REASON SCV, refer to the IAF guide that applies to your operating system.

Examples
MODIFY TABLE_FIELD ORDER_LINES(TOTAL_VALUE) & /ADD_TRIGGER=(ORDERS(TOTAL_VALUE)=ORDERS(TOTAL_VALUE + #GM_DELTA)

MODIFY TABLE_FIELD CUSTOMERS(NAME) & /AUDIT=MODIFY,DELETE MODIFY TABLE_FIELD WAREHOUSE(DESCRIPTION) & /AUDIT=NONE

10-90

DML Metadata Commands IAF 8.0 DML

START_METADATA_BATCH

START_METADATA_BATCH
Syntax
START_METADATA_BATCH [/HANDLE=<db_handle>][/TRANSACTION_AREA=<trans_area>]

Description
Certain metadata modifications, such as changes to datatype definitions, carry heavy processing overheads on some engines (e.g. ORACLE). This metadata command and its corresponding END_METADATA_BATCH can improve the efficiency of multiple metadata updates being done simultaneously to the same database (e.g. during an application upgrade). The effect of these commands is to consolidate and optimize the order of application of a set of changes to the database. IAF does not implement metadata batching on all engines. If this command is issued against an engine that does not support it, no error will be generated and the command will be ignored. Note: When using certain engines (e.g. ORACLE) modifying a datatype will cause IAF to internally batch the datatype modification and subsequent field/table modifications associated with it .

Qualifiers
The following qualifiers are valid for use with the START_METADATA_BATCH metadata command:

/HANDLE
This qualifier specifies the database to which the metadata batching is to be applied. If no /HANDLE is specified, then the current database is assumed.

/TRANSACTION_AREA
This qualifier specifies a particular named area to be used for transactions related to the database changes in the batch. The value of trans_area is DBMS-specific. (For example, for an ORACLE database it will specify a particular rollback segment.)

DML Metadata Commands IAF 8.0 DML

10-91

START_METADATA_BATCH

Additional information
After this command is executed, some of the subsequent metadata commands for this database will be accumulated for later execution in a batch. The END_METADATA_BATCH statement signifies the end of the batch. Not all metadata commands are deferred, only those for which optimization can be achieved by batching, such as datatype updates. Once a START_METADATA_BATCH command has been executed, metadata changes will be processed in one of three ways. Processed immediately. This includes all IAF-only metadata updates except for datatype and field modifications. Batched. This includes datatype, field, and table modifications. These changes will be accumulated for processing later when the batch is complete. Some datatype and field modifications which only affect IAF-specific metadata (e.g. changing a field heading) could be processed immediately but they are instead included in the batch to make error recovery simpler. (If the batch update fails for any reason, the user does not have to work out which part of the datatype or field modification has to be resubmitted. Note: Qualifiers exist on the INVOKE statement to assist with recovering from a failed batch update.) Rejected. Some commands cannot easily be processed within a metadata batch, so they are disallowed. It can be extremely difficult to determine the sequence in which certain commands should be implemented to ensure that the correct definitions are used throughout. Disallowed commands include ADD and DELETE for tables, views and indices.

10-92

DML Metadata Commands IAF 8.0 DML

Appendix A

Input and Output Masks

Introduction

Introduction
A mask is a literal specification that indicates the input or output format for a piece of raw data. Input masks indicate how IAF is to format raw data during and after data entry. Output masks indicate how IAF is to format raw data when printing or displaying it. The result is a translated data string to output or subsequently process. Masks used within DML programs must be enclosed within quotes. However, masks used in response to IAF utility prompts (e.g. when defining datatypes and fields) should not be enclosed in quotes. This chapter uses quotes to delimit its examples and uses a tilde (~) to denote each space in the mask and result given for each example. This chapter describes input masks and output masks, and text, numeric, and date masking.

A-2

Input and Output Masks IAF 8.0 DML

Input Masks

Input Masks
An input mask specifies a given fields format and the number of characters in the field.

Example
Given the following mask, IAF determines that the input area of the field to which the mask is applied is 10 characters in length. Note that the field does not actually hold the characters (, ), and -. However, they display as a result of the mask.
Mask : Data : Result : !(@@@)@@@-@@@@ 7607456006 (760)745-6006

Input and Output Masks IAF 8.0 DML

A-3

Output Masks

Output Masks
In addition to optionally specifying an output mask when you define a field via the Data Definition Editor, you can use output masks from within IAF via the following DML constructs: The /OUTPUT_MASK qualifier which applies to input and output blocks. For details on the /OUTPUT_MASK qualifier, refer to this manuals BLOCKS AND BLOCK QUALIFIERS chapter. The MASK built-in function. For details on the MASK function, refer to this manuals BUILT-IN FUNCTIONS chapter. For both constructs, the mask specification can be any valid DML expression whose value is a valid mask specification, according to the rules that this chapter presents. For details on expressions, refer to this manuals EXPRESSIONS chapter. Output masking involves the substitution of raw data for a series of predefined tokens in a given mask to form an output string. Within this context, IAF performs numeric, text, and date masking. A numeric mask is a mask that contains both the right-justification symbol (-) and the radix symbol (.) and is value-oriented instead of character-oriented. A text mask is similar to a numeric mask in appearance except that it contains only one of the aforementioned characters, or neither of them. A text masks function is quite different from a numeric masks function in that text masking involves data substitution on a character-by-character basis. A date mask is a mask that contains special date tokens as described in this chapters Date Masking section. Date masking replaces special date tokens in a given mask with parts of the given raw date data. Note that for date masking, the raw date data must be in the format DD-Mon-YYYY [HH:MM:SS.CC].

A-4

Input and Output Masks IAF 8.0 DML

Text and Numeric Masking

Text and Numeric Masking

Text and numeric masks share many of the same features. However, the defining feature of a numeric mask is that it contains both the rightjustification symbol (-) and the radix symbol (.). This section details text and numeric masking features.

Beginning a Mask
An exclamation point (!) or the first occurrence of a replaceable character denotes the beginning of a mask. However, it is preferable to use an exclamation point to denote the beginning of each mask. This practice results in consistent, easily-recognizable masks.

Text Replacement Character

The general text replacement character in a mask is the @ character. As a result of applying a given mask, IAF replaces every occurrence of this character with raw data in the output string, unless a backslash (\) precedes the @ character. For details on the backslashs role in a mask, refer to this sections Protection of Substitute Characters heading.

Right-Justification Symbol
Following a masks exclamation point (see this sections Beginning a Mask heading) with an optional hyphen (-) indicates that the data is to be right-justified within the mask that follows. IAF trims all trailing spaces from the data string before masking it. Right justification is typical when masking numeric data.

Example
Mask Data Result : : : !-@@@@@ 123 ~~123

Input and Output Masks IAF 8.0 DML

A-5

Text and Numeric Masking

Radix Symbol
If a given mask contains a radix symbol (.) and a right-justification symbol (-), IAF treats any data to which it applies the mask as numeric (see this sections Right-Justification Symbol heading). If the data contains a radix symbol, IAF aligns the two radix symbols. If the mask and or data contains more than one radix symbol, IAF assumes that the right-most occurrence indicates the true radix. The default output radix symbol is a decimal point (.). However, you can define an operating system dependent System Customization Variable (SCV) to override the default radix symbol. To determine the SCV that enables you to override the default radix symbol on a particular operating system upon which IAF runs, refer to the IAF guide that applies to that operating system. Note that regardless of whether you change the default output radix symbol, the radix symbol for use within masks remains the decimal point (.).

Examples
Mask : Data : Result : Mask : Data : Result : !-0@@.@@@ 1.1 001.100 !-@@@.@@@ 1 ~~1.~~~

Suppression of a Trailing Radix Symbol

A radix symbol indicates the proper alignment for given numeric data. A special case arises when a numeric mask accommodates only whole values. The mask must still contain a radix symbol for IAF to treat data to which the mask is applied as numeric and to ensure that IAF rounds the data to a whole number. However, IAF suppresses the trailing radix in the output data by default.

Examples
Mask : Data : Result : Mask : Data : Result : Mask : Data : Result : !-@@@@. 1.5 ~~~2 !-@@@@ 1.5 ~1.5 !-@@@@.\. 1.5 ~~~2.

A-6

Input and Output Masks IAF 8.0 DML

Text and Numeric Masking

Digit Separator Symbol

A digit separator symbol (,) in a numeric mask indicates the location in which IAF is to place the currently set digit separator. The default output digit separator symbol is a comma (,). However, you can define an operating system dependent System Customization Variable (SCV) to override the default digit separator symbol. To determine the SCV that enables you to override the default digit separator symbol on a particular operating system upon which IAF runs, refer to the IAF guide that applies to that operating system. Note that regardless of whether you change the default output digit separator symbol, the digit separator symbol for use within masks remains the comma (,).

Examples
Mask : Data : Result : Mask : Data : Result : !-@@@,@@@.@@ 1345 ~~1,345.~~ !-@@@,@@@.@@ 1.1 ~~~~~~1.1~

Protection of Substitute Characters

To prevent IAF from replacing a mask character that IAF normally treats as a replaceable character, precede the character by a backslash (\).

Example
Mask : Data : Result : !@@\@-@@\@-@@ 123456 12@-34@-56

Null String Masks

If the mask is a null string, IAF uses a default mask, consisting entirely of @ characters. The default masks length is the same as the given datas length.

Input and Output Masks IAF 8.0 DML

A-7

Text and Numeric Masking

Blank Symbol
Preceding a masks replaceable characters with a circumflex (^) indicates that if the source string is null, blank, or has a numeric value of zero, the output string is to be blank.

Example
Mask : Data : Result : !-^@@@.@@@ ~~~~~~~

Data Larger than Mask

If the length of the source string exceeds the number of replaceable characters in a given mask, the percent sign (%) replaces each replaceable character in the output string.

Example
Mask : Data : Result : !@@@@ 12345 %%%%

Rounding on Numeric Masks

IAF rounds to the number of decimal places that a given numeric mask indicates.

Example
Mask : Data : Result : !-@@@.@@ 1.235 1.24

Zero Filling
A zero character (0) in a mask indicates that zero filling of spaces is to take place. IAF sets to zeros the indicated position and any positions to the right of it if those positions would otherwise be blank. Note that zero (0) is a replaceable character.

Examples
Mask : Data : Result : Mask : Data : Result : !-0@@@@@ 1 000001 !-$@@@@0.@@@ 12.4 ~~~$12.400

A-8

Input and Output Masks IAF 8.0 DML

Text and Numeric Masking

Zero Suppression
A semi-colon (;) in a mask indicates that zero suppression is to take place. If the mask is a text mask, IAF sets to spaces any zeros in the indicated position and in any positions to the right of the indicated position, including any zeros generated by the zero filling character (see this sections Zero Filling heading). If the mask is a numeric mask, the semi-colon (;) has no effect unless it is in the mask portion after the radix symbol (.). If the semi-colon (;) is in the mask portion after the radix symbol (.), IAF sets to spaces any zeros in the indicated position and in any positions to the right of the indicated position, including any zeros generated by zero filling (see this sections Zero Filling heading), only if the zeros are trailing zeros. Note that the semi-colon (;) is a replaceable character.
Examples Mask : Data : Result : Mask : Data : Result : Mask : Data : Result : Mask : Data : Result : Mask : Data : Result : Mask : Data : Result : !-@@@;@ 2704 ~27~4 !-@@@;@ 2700 ~27~~ !-@@@@0@;@.@@ 270 ~~~~0270.~~ !-@@@@0@@@.;@ 271.04 ~~~~0271.04 !-@@@@0@@@.;@ 271.40 ~~~~0271.4~ !-@@@@@0.@;@@ 345 ~~~345.0~~~

Input and Output Masks IAF 8.0 DML

A-9

Text and Numeric Masking

Currency Symbol
A mask may include a dollar sign ($) or pound sign (#) at any point to indicate a currency sign. This causes the currently set currency sign to precede the first non-blank output character. The default output currency sign is the dollar sign ($). However, you can define an operating system dependent System Customization Variable (SCV) to override the default currency sign. To determine the SCV that enables you to override the default currency sign on a particular operating system upon which IAF runs, refer to the IAF guide that applies to that operating system. Note that regardless of whether you change the default output currency symbol, the currency symbol for use within masks remains the dollar sign ($) or the pound sign (#).

Example
Mask : Data : Result : !-$@@@@ 12 ~~$12

Asterisk Filling
An asterisk (*) in the mask indicates that IAF is to replace with an asterisk each location that would otherwise be blank, starting from the left and continuing up to the first non-blank output character. Note that the asterisk is a replaceable character.

Examples
Mask : Data : Result : Mask : Data : Result : !-*@@@@@ 1 *****1 !-*@@@@@ 123456 123456

A-10

Input and Output Masks IAF 8.0 DML

Text and Numeric Masking

Masking Hierarchy
IAF performs mask operations in the following order when applying a given mask: zero filling/suppression currency symbol substitution asterisk filling

Examples
Mask : Data : Result : Mask : Data : Result : !-*$@@@@@ 1 *****$1 !-0$@@@@@ 1 $000001

Input and Output Masks IAF 8.0 DML

A-11

Text and Numeric Masking

Text Substitution Tokens

The !TX and !AS text substitution tokens are available for use in masks. They are functionally similar, except that the !TX token is casesensitive and the !AS token is not. The !TX token produces masked data whose case matches the case of the token, whereas the !AS token produces masked data whose case matches the case of the unmasked data. IAF removes all trailing spaces and tabs from the data, prior to substituting the data for the !TX or !AS token. The general formats for these tokens is !-nnnTX and !-nnnAS, where the optional - symbol indicates right-justification, and the optional nnn is a value indicating a length for a fixed length substitution. If a given !TX or !AS token does not include a fixed length value, the substitution length is the same as the data length. Note that masks containing !TX and !AS tokens do not return errors for data overflow conditions. Instead the data truncates to fit the token. The !TX and !AS tokens are not valid for use with date tokens (see this chapters Date Masking section).

Examples
Mask : Data : Result : Mask : Data : Result : Mask : Data : Result : Mask : Data : Result : Mask : Data : Result : Mask : Data : Result : Department~!Tx~is~OK SYS Department~Sys~is~OK Department~!4AS~is~OK sYs Department~sYs~~is~OK Department~!2tx~is~OK SYS Department~sy~is~OK Department~!-2TX~is~OK sys Department~YS~is~OK Department~!-tX~is~OK sys Department~sYS~is~OK Department~!-5tx~is~OK SYS Department~~~sys~is~OK

A-12

Input and Output Masks IAF 8.0 DML

Text and Numeric Masking

Value Tokens
An optional value token may follow the body of a mask to indicate an action that IAF is to perform conditionally depending upon whether the given numeric value is positive or negative. The table on the following page lists and describes the effects of the value tokens that are valid for use in masks. Value token: trailing hyphen (-) Effect if numeric value is negative: IAF places the trailing hyphen (-) in the output string to serve as a negative sign. IAF places CR in the output string to indicate a credit. IAF replaces DB with two spaces in the output string. IAF places DR in the output string to indicate a debit reduction. IAF encloses the output string in parentheses. Effect if numeric value is positive: IAF replaces the trailing hyphen (-) with a space in the output string. IAF replaces CR with two spaces in the output string. IAF places DB in the output string to indicate a debit. IAF replaces DR with two spaces in the output string. IAF places a leading space and a trailing space in the output string in lieu of enclosing the output string in parentheses. IAF places a leading space and a trailing space in the output string in lieu of enclosing the output string in angle brackets.

CR

DB

DR

()

<>

IAF encloses the output string in angle brackets.

Input and Output Masks IAF 8.0 DML

A-13

Text and Numeric Masking

Examples
Mask : Data : Result : Mask : Data : Result : Mask Data : : !-*@0.@@@- -1.1 **1.100- !-@@@.@@@CR -1.1 ~~1.1~~CR !-@@@.@@@() -111.111 Result:(111.111) !-@@@.@@@() 111.111 ~111.111~

Mask : Data : Result :

No Value Token
If no value token (see this sections Value Tokens heading) follows the body of a given mask, and the data to mask is a negative number, IAF replaces one of the masks replaceable characters with a negative sign (-) in the output string. The negative sign appears immediately before the first non-blank character in the output string.

Example
Mask : Data : Result : !-@@@0.@@ -1.1 ~~-1.10

A-14

Input and Output Masks IAF 8.0 DML

Date Masking

Date Masking
A date mask contains one or more date tokens that facilitate special date/ time manipulation. Data to which a date mask is to be applied must be in the format DD-Mon-YYYY [HH:MM:SS.CC]. If the given data does not include a time specification, the default time specification is 00:00:00.00. Likewise, the default value for a time component that a given time does not include (hundredths of a second) is 00. An exclamation point (!) must precede each IAF date token in a date mask. Optionally, a minus sign (-) may follow the exclamation point to indicate right-justification (the default is left-justification), and/or a positive integer may follow the exclamation point to indicate a field width shorter or longer than the default width for the given token. Note that many of the date tokens are case-sensitive (for example; the case of the output substitution corresponds to the case of the token). Also note that a given mask can use each token once, more than once, or not at all, as required. If an error occurs while performing date masking (e.g. the source string is not a valid date), IAF fills the output string with % characters. The remainder of this section provides details regarding the date tokens that are available for use when performing date masking.

AP
This token represents the literal AM or PM depending upon the time given in the source date. This token is case-sensitive. Therefore, the case of the output matches the case of the first letter of the token as the following examples illustrate.

Examples
Mask : Data : Result : Mask : Data : Result : !AP 18-Apr-1993 18:52:45 PM !-10ap 18-Apr-1993 ~~~~~~~~am

Input and Output Masks IAF 8.0 DML

A-15

Date Masking

CC
This token represents a two-digit, zero-filled number in the range 00-99 indicating hundredths of a second.

Example
Mask : Data : Result : !CC 01-Jan-1994 01:23:24.03 03

DD
This token represents a two-character, space-filled number in the range 131 indicating the day of the month.

Examples
Mask : Data : Result : Mask : Data : Result : Mask : Data : Result : !DD 01-Dec-1993 ~1 !DD 15-Mar-1994 15 !10DD 18-Feb-1994 18~~~~~~~~

DJ
This token represents a three-digit, zero-filled number in the range 001365 indicating the day of the year.

Examples
Mask : Data : Result : Mask : Data : Result : Mask : Data : Result : !DJ 01-Jan-1991 001 !DJ 01-Mar-1991 060 !DJ 01-Mar-1992 061 (because of leap year)

A-16

Input and Output Masks IAF 8.0 DML

Date Masking

DZ
This token represents a two-digit, zero-filled number in the range 01-31 indicating the day of the month.

Examples
Mask : Data : Result : Mask : Data : Result : !DZ 01-Feb-1994 01 !DZ 23-Feb-1994 23

HH
This token represents a two-digit, zero-filled number in the range 00-23 indicating the hour of the day according to the 24-hour clock.

Examples
Mask : Data : Result : Mask : Data : Result : !HH 18-Apr-1993 09:52:45 09 !HH 27-Nov-1993 21:03 21

IT
This token represents the time of the day in the format HH:MM according to the 24-hour clock.

Examples
Mask : Data : Result : Mask : Data : Result : !IT 05-Jul-1993 18:52:45 18:52 !IT 05-Jul-1993 03:45:59 03:45

Input and Output Masks IAF 8.0 DML

A-17

Date Masking

LD
This token represents the complete name of the day of the week (see also this sections description of the SD token). This token is case-sensitive. Therefore, the case of the output matches the case of the token as the following examples illustrate.

Examples
Mask : Data : Result : Mask : Data : Result : Mask : Data : Result : Mask : Data : Result : !LD 30-Apr-1994 SATURDAY !ld 30-Apr-1994 saturday !Ld 30-Apr-1994 Saturday !lD 30-Apr-1994 sATURDAY

LM
This token represents the complete name of the month (see also this sections description of the SM token). This token is case-sensitive. Therefore, the case of the output matches the case of the token as the following examples illustrate.

Examples
Mask : Data : Result : Mask : Data : Result : Mask : Data : Result : Mask : Data : Result : !LM 30-Apr-1994 APRIL !lm 30-Apr-1994 april !Lm 30-Apr-1994 April !lM 30-Apr-1994 aPRIL

A-18

Input and Output Masks IAF 8.0 DML

Date Masking

LY
This token represents a four-digit number indicating the year (see also this sections description of the YY token).

Example
Mask : Data : Result : !LY 18-Sep-1993 18:52:45 1993

MI
This token represents a two-digit, zero-filled number in the range 00-59 indicating the minute of the hour.

Examples
Mask : Data : Result : Mask : Data : Result : !MI 30-Oct-1993 18:04:45 04 !MI 30-Oct-1993 18:32:22 32

MM
This token represents a two-digit, zero-filled number in the range 01-12 indicating the month.

Examples
Mask : Data : Result : Mask : Data : Result : !MM 27-Feb-1994 22:52:45 02 !MM 17-Dec-1993 12

Input and Output Masks IAF 8.0 DML

A-19

Date Masking

SD
This token represents the name of the day of the week abbreviated to three characters (see also this sections description of the LD token). This token is case-sensitive. Therefore, the case of the output matches the case of the token as the following examples illustrate.

Examples
Mask : Data : Result : Mask : Data : Result : Mask : Data : Result : Mask : Data : Result : !SD 30-Apr-1994 SAT !sd 30-Apr-1994 sat !Sd 30-Apr-1994 Sat !sD 30-Apr-1994 sAT

SH
This token represents a two-character, space-filled number in the range 01-12 indicating the hour of the day according to the 12-hour clock.

Examples
Mask : Data : Result : Mask : Data : Result : Mask : Data : Result : Mask : Data : Result : !SH 22-Aug-1993 01:52:45 ~1 !SH 22-Aug-1993 12:35 12 !SH 22-Aug-1993 00:23:45 12 !SH 22-Aug-1993 23:02:22 11

A-20

Input and Output Masks IAF 8.0 DML

Date Masking

SM
This token represents the name of the month abbreviated to three characters (see also this sections description of the LM token). This token is case-sensitive. Therefore, the case of the output matches the case of the token as the following examples illustrate.

Examples
Mask : Data : Result : Mask : Data : Result : Mask : Data : Result : Mask : Data : Result : !SM 30-Apr-1994 APR !sm 30-Apr-1994 apr !Sm 30-Apr-1994 Apr !sM 30-Apr-1994 aPR

SS
This token represents a two-digit, zero-filled number in the range 00-59 indicating the seconds of the minute.

Examples
Mask : Data : Result : Mask : Data : Result : !SS 11-May-1993 23:18:02 02 !SS 11-May-1993 23:18:34 34

Input and Output Masks IAF 8.0 DML

A-21

Date Masking

YY
This token represents a two-digit, zero-filled number indicating the last two digits of the year.

Examples
Mask : Data : Result : Mask : Data : Result : !YY 21-Jan-1994 18:52:45 94 !YY 21-Jan-1901 18:52:45 01

A-22

Input and Output Masks IAF 8.0 DML

Appendix B

Executing DML Statements Via Qualifiers

Introduction

Introduction
Certain DML statement and construct qualifiers enable you to specify a DML statement that IAF is to execute under a pre--defined condition. For example, the /ITEM block qualifier enables you to specify a DML statement that IAF is to execute if an end user selects the given item on a menu block. Likewise, the FETCH statements /FAILURE qualifier enables you to specify a DML statement that IAF is to execute if the FETCH statement fails (for example; there are no records left to fetch from the given stream). However, some DML statements cannot be executed via qualifiers. Following is an alphabetical list of DML statements that can be executed via qualifiers.
ADD BEGIN_DISABLE_TRIGGER BEGIN_SIGNAL_TO_STATUS CALL CLEAR_BUFFER CLI CLOSE_TEXT COMMIT CONNECT CONTINUE DCL DELETE DISCONNECT DISPLAY END_DISABLE_TRIGGER END_EXECUTE END_SIGNAL_TO_STATUS ERROR EXECUTE EXIT FIND GOTO RECEIVE_DATA REPOSITION REWIND_TEXT ROLLBACK SEND_DATA SEND_MESSAGE SET START_TRANSACTION SWITCH SWITCH_BASE UNLOAD WRITE WRITE_LINE LOAD MAIL MENU MESSAGE OPEN_TEXT PERFORM PRINT READ_LINE

B-2

Executing DML Statements Via Qualifiers IAF 8.0 DML

Introduction

In addition to these DML statements, assignment statements (for example; #A=abc) can also be executed via qualifiers. For details regarding the DML statements listed above, other DML statements, and DML statement qualifiers, refer to this manuals LANGUAGE STATEMENTS chapter. For details regarding block constructs and block qualifiers, refer to this manuals Blocks and Block Qualifiers chapter.

Executing DML Statements Via Qualifiers IAF 8.0 DML

B-3

Appendix C

Predefined Stored Procedures

Introduction

Introduction
The DML EXECUTE statement can execute user-defined stored procedures and any of IAFs predefined stored procedures. Names of IAF predefined stored procedures begin with the reserved prefix GEM_ (user-defined stored procedure names cannot use this prefix). This chapter describes IAFs predefined stored procedures and provides examples of their use. For details on user-defined stored procedures, refer to the discussion of the Data Definition Editor in the IAF System Reference Manual, and the discussion of the ADD PROCEDURE metadata command in this manuals METADATA COMMANDS chapter. For details on the EXECUTE statement, refer to this manuals Language Statements chapter.

GEM_COMMIT()
This predefined stored procedure makes permanent all database updates that have taken place since the current stored procedure transaction began via the GEM_START_TRANSACTION predefined stored procedure. For details on GEM_START_TRANSACTION, refer to its description in this appendix.

GEM_EXECUTE_DML(dml_string)
This predefined stored procedure facilitates executing a DML statement via a stored procedure server, where dml_string is a string indicating the DML statement to execute. The statement should be one that performs a cohesive function independent of other statements.

GEM_GET_PARAMETER(output_value,parameter_name[,parameter_date])
This predefined stored procedure returns the current value of the specified parameter, where output_value indicates the entity (typically a variable) in which to return the value, and parameter_name is the name of the parameter for which to return the value. A parameter can be defined relative to a date range. Therefore, you can optionally include a date argument (parameter_date) in the format DD-Mon-YYYY to indicate the date for which to return data. For details on parameters, refer to the discussion of the Data Definition Editor in the IAF System Reference Manual and the discussion of the ADD PARAMETER metadata command in this manuals Metadata Commands chapter.

C-2

Predefined Stored Procedures IAF 8.0 DML

Introduction

GEM_GET_TEXT(output_value,message_name[,argument[,...]])
This predefined stored procedure returns the current value of the specified message, where output_value indicates the entity (typically a variable) in which to return the value, and message_name is the name of the message for which to return the value. Optionally, you may also specify any argument(s) to substitute on a character-by-character basis for any mask token(s) in the message. For details on messages, refer to the discussion of the Data Definition Editor in the IAF System Reference Manual and the discussion of the ADD MESSAGE metadata command in this manuals Metadata Commands chapter.

GEM_ROLLBACK()
This predefined stored procedure rolls back all database updates that have taken place since the current stored procedure transaction began via the GEM_START_TRANSACTION predefined stored procedure. For details on GEM_START_TRANSACTION, refer to its description in this appendix.

GEM_START_TRANSACTION(type)
This predefined stored procedure starts a stored procedure transaction of the given type, where 0 indicates a read/write transaction, and 1 indicates a read-only transaction. By default, a transaction completes for each stored procedure execution, and therefore, it is not possible to ensure data integrity. However, by using GEM_START_TRANSACTION in conjunction with the GEM_COMMIT and GEM_ROLLBACK predefined stored procedures, it is possible to override this behavior and control the number of operations that take place within each transaction. For details on GEM_COMMIT and GEM_ROLLBACK, refer to their descriptions in this appendix.

Examples
Example 1:
CONNECT MANUFACTURING EXECUTE . . EXECUTE . . EXECUTE . . EXECUTE GEM_START_TRANSACTION(0)

ADD_RECORD(#FIELD1,#FIELD2,#FIELD3)

ADD_RECORD(#FIELD1,#FIELD2,#FIELD3)

GEM_COMMIT

DISCONNECT MANUFACTURING

Predefined Stored Procedures IAF 8.0 DML

C-3

Introduction

Example 2:
EXECUTE GEM_EXECUTE_DML (ADD PROCEDURE CUST_LOOKUP & /DESCRIPTION=customer lookup & /FILE_NAME=app:cust_lookup & /PARAMETER=CUSTOMER_ID & /DATATYPE=TEXT & /LENGTH=6 & /PASS=VALUE & /PARAMETER=CUSTOMER_NAME & /DATATYPE=TEXT & /LENGTH=30 & /PASS=REFERENCE )

C-4

Predefined Stored Procedures IAF 8.0 DML

Appendix D

Interactive Debugger For DML Code

Introduction

Introduction
This appendix describes the DML interactive debugger, which enables you to debug DML code while executing it. The DML interactive debugger can display the DML code during execution and allows you to set break points in the program. At those break points, the debugger enables you to examine the contents of variables, tables, and fields. The DML interactive debugger is intended primarily for individuals who program directly in the DML, or who are familiar with the DMLs syntax, statements, and constructs.

Operation
Invoking the Debugger
You can invoke the DML interactive debugger by: using the SET DEBUG ON command in conjunction with the PERFORM statement. If you execute the SET DEBUG ON command from within IAF, and subsequently enter a PERFORM statement at the IAF command line prompt (GEM> by default), IAF displays the debugger command line prompt (GDBG>) to enable you to set debugger options, such as break points, before executing the specified form. For more information regarding the SET DEBUG command, refer to this sections SET DEBUG Command heading. For details regarding the PERFORM statement, refer to this manuals LANGUAGE STATEMENTS chapter. using the CTRL/C key sequence while executing a form. This causes the form to stop executing and control to pass to the debugger when the next DML statement in the form executes. IAF displays the debugger command line prompt (GDBG>) to indicate that the debugger is ready to accept commands. You can enter any valid debug command at the GDBG> prompt. For details regarding the debug commands that are available, refer to the Debug Commands section of this appendix.

D-2

Interactive Debugger For DML Code IAF 8.0 DML

Operation

SET DEBUG Command

The SET DEBUG command facilitates enabling and disabling the DML interactive debugger from within IAF. The syntax for the SET DEBUG command is as follows:
SET DEBUG keyword

where keyword is one of the keywords that the table on the following page lists and describes. SET DEBUG Keywords Keyword NONE Description This keyword disables the debugger, which remains disabled until it is explicitly turned on via the SET DEBUG ON command. While the debugger is disabled, pressing CTRL/C from within a form does not invoke the debugger, and executing a form via the PERFORM statement does not display the debugger command line prompt (GDBG>). This keyword turns off the debugger. While the debugger is off, executing a form via the PERFORM statement does not display the debugger command line prompt. However, pressing CTRL/C from within a form still invokes the debugger. This keyword enables the debugger so that subsequently entering a PERFORM statement at the IAF command line prompt (GEM> by default) causes IAF to display the debugger command line prompt. This facilitates setting debugger options, such as break points, before executing the specified form. Pressing CTRL/C from within a form while the debugger is enabled invokes the debugger. However, it is not necessary for the debugger to be enabled for CTRL/C to have this effect. Pressing CTRL/C from within a form invokes the debugger as long as the debugger is not disabled (see NONE keyword above).

OFF

ON

Interactive Debugger For DML Code IAF 8.0 DML

D-3

Cancel

Cancel
Syntax
CANCEL keyword

Description
This command allows you to cancel various debugger settings.

Keywords
The following table lists and describes the keywords that are valid for use with the CANCEL command. Keyword ALL BREAK Description This keyword facilitates canceling all break and watch points that are currently set. This keyword facilitates canceling a break point set via a SET BREAK debug command. Valid formats for the CANCEL BREAK command are as follows: CANCEL BREAK %LINE nnnn CANCEL BREAK form_name CANCEL BREAK/ALL WATCH Cancels a break point at the given line number. Cancels a break point at the start of the given form. Cancels all break points.

This keyword facilitates canceling a watch point set via a SET WATCH debug command. Valid formats for the CANCEL WATCH command are as follows CANCEL WATCH #variable Cancels a watch point on the given variable. This format is valid only from within the form that set the watch point. Cancels a watch point on the given array element. This format is valid only from within the form that set the watch point.

CANCEL WATCH #array(element)

D-4

Interactive Debugger For DML Code IAF 8.0 DML

Cancel

Keyword CANCEL WATCH table_name(field_name) WATCH

Description Cancels a watch point on the given table field. Cancels a watch point on the given table field in the indicated database. Cancels a watch point on the given table field in the indicated stream. This format is valid only from within the form that set the watch point. Cancels all watch points.

CANCEL WATCH database_handle.table_name(field_nam e) CANCEL WATCH stream_name:table_name(field_name)

CANCEL WATCH/ALL

Examples
CANCEL BREAK %LINE 4 CANCEL WATCH #bonus_flag

Interactive Debugger For DML Code IAF 8.0 DML

D-5

Deposit

Deposit
Syntax
DEPOSIT #variable=value DEPOSIT #array(element)=value DEPOSIT table_name(field_name)=value DEPOSIT stream_name:table_name(field_name)=value DEPOSIT database_handle.table_name(field_name)=value

Description
This command enables you to place a value in a variable, array element, or table field. The given value may be an integer, a floating point number, or a quoted string. When placing a value into a variable or array element, the variable or array element takes on the datatype of the value.

Examples
DEPOSIT #A=1 DEPOSIT #B(2)=2.51 DEPOSIT ORDERS(CUSTOMER_ID)=RPA1123

D-6

Interactive Debugger For DML Code IAF 8.0 DML

Examine

Examine
Syntax
EXAMINE symbol

Description
This command examines the specified symbol and returns its value.

Symbols
The following table lists and describes the symbols that are valid for use with the EXAMINE command. Symbol #variable #array(nnn) table_name(field_name) database_handle.table_name(field_na me) stream_name:table_name(field_name) %STATUS Description A DML variable or form argument. A DML array element. Note that nnn must be a constant. A field in any table in the current default database. A field in any table in the given database. A field in a table in the given stream. The IAF special variable that indicates the completion status of the last DML operation. For details regarding %STATUS, refer to this manuals Special Variables And Value Symbols chapter.

Interactive Debugger For DML Code IAF 8.0 DML

D-7

Examine

Symbol %TRANS_LEVEL

Description The IAF special variable that indicates the number of transactions that are currently outstanding. For details regarding %TRANS_LEVEL, refer to this manuals Special Variables And Value Symbols chapter.

Examples
EXAMINE #log_numbers(3) EXAMINE CUSTOMERS(REGION) EXAMINE VIDEOS.MOVIES(MOVIE_TITLE)

D-8

Interactive Debugger For DML Code IAF 8.0 DML

Exit

Exit
Syntax
EXIT

Description
This command halts execution of the current form and returns control to either the IAF command line prompt (GEM> by default) or to a system level menu, depending upon the origin of the current forms execution.

GO
Syntax
GO [/TRACE]

Description
This command continues execution of the current form until the form ends naturally or a break point is reached.

Qualifier
You can append the following qualifier to the GO command:

/TRACE
This qualifier produces a continuous display of the given DML source file as its lines execute.

Interactive Debugger For DML Code IAF 8.0 DML

D-9

HELP

HELP
Syntax
HELP [help_topic]

Description
This command invokes the DML debuggers on--line help library. If a valid help topic is given, the debugger displays help pertaining to that topic. If no help topic is given, the debugger displays a list of help topics that are available and prompts you to specify a help topic to display.

Examples
HELP SET HELP CANCEL ALL

PRINT
Syntax
PRINT symbol

Description
This command is functionally identical to the EXAMINE command. For details regarding this commands operation, refer to the description of the EXAMINE command in this appendix.

D-10

Interactive Debugger For DML Code IAF 8.0 DML

QUIT

QUIT
Syntax
QUIT

Description
This command aborts execution of the current form and returns control to either the IAF command prompt or to a system level menu, depending upon the origin of the current forms execution

Interactive Debugger For DML Code IAF 8.0 DML

D-11

SCROLL

SCROLL
Syntax
SCROLL /qualifier

Description
If the debugger source code window is currently enabled (see the description of the SET MODE SCREEN debug command), this command displays source code that is not currently visible on the screen by scrolling in the direction that the given qualifier indicates.

Qualifiers
You can append one of the following qualifiers to the SCROLL command:

/DOWN
This qualifier causes the debugger to display source code that resides on lines following the currently displayed source code lines.

/LEFT
This qualifier causes the debugger to display source code to the left of the currently displayed source code. Specifically, this qualifier causes the display of source code to shift eight characters to the left.

/RIGHT
This qualifier causes the debugger to display source code to the right of the currently displayed source code. Specifically, this qualifier causes the display of source code to shift eight characters to the right.

/UP
This qualifier causes the debugger to display source code that resides on lines preceding the currently displayed source code lines.

D-12

Interactive Debugger For DML Code IAF 8.0 DML

SEARCH

SEARCH
Syntax
SEARCH [search_string]

Description
This command searches the current DML source code for an occurrence of the specified search string. If the debugger locates an occurrence of the string, the debugger displays the number of the line on which it found the string. If no search string specification is given, the debugger searches for an occurrence of the last specified search string starting from the point at which the string was last found.

Example
SEARCH #item_no

Interactive Debugger For DML Code IAF 8.0 DML

D-13

SET

SET
Syntax
SET keyword

Description
This command enables you to set various debugger options.

Keywords
The following table lists and describes the keywords that are valid for use with the SET command. Keyword BREAK Description This keyword facilitates setting a break point. The debugger halts execution of the given form upon reaching the break point, and returns control to the debugger command line. Valid formats for the SET BREAK command are as follows: SET BREAK %LINE nnn Sets a break point at the source line that the value nnn indicates. The specified source line must be a line within the current form.

D-14

Interactive Debugger For DML Code IAF 8.0 DML

SET

Keyword

Description SET BREAK form_name Sets a break point at the start of the given form. The form does not have to reside in the current source file. However, if it does not, the debugger displays a warning message. Sets a break point at any point in the form where an error condition causes IAF to display an error message.

BREAK

SET BREAK/EXCEPTION

MODE

This keyword facilitates turning on and off the debugger source code window. Valid formats for the SET MODE command are as follows: SET MODE SCREEN Turns on the window in which the debugger displays the DML code for the current form.

Interactive Debugger For DML Code IAF 8.0 DML

D-15

SET

Keyword

Description SET MODE NOSCREEN Turns off the window in which the debugger displays the DML code for the current form.

SOURCE

This keyword facilitates setting the source to be debugged to a specified file. By default the DML source files name and directory information reside in the header of the compiled DML file (filetype .dmc). The SET SOURCE command enables you to override the default. The valid format for the SET SOURCE command is as follows: SET SOURCE file_specification

WATCH

This keyword facilitates setting a watch point on a variable, array element, or table field. The debugger halts execution of the given form when the contents of the watched entity change, and displays both the old and new values of the watched entity. Note that setting watch points slows down the execution of DML code considerably. Valid formats for the SET WATCH command are as follows: SET WATCH #variable Sets a watch point for the specified variable. This formats scope is the current DML form. Therefore, its effect is terminated if the given form exits.

D-16

Interactive Debugger For DML Code IAF 8.0 DML

SET

Keyword Watch

Description SET WATCH #array(element) Sets a watch point for the specified array element. This formats scope is the current DML form. Therefore, its effect is terminated if the given form exits. Sets a watch point for the specified table field in the current default database. This formats scope is all DML forms. Sets a watch point for the specified table field in the specified database. This formats scope is all DML forms.

SET WATCH table_name(field_name)

SET WATCH database_handle.table_name(field_name)

Interactive Debugger For DML Code IAF 8.0 DML

D-17

SET

Keyword

Description SET WATCH stream_name:table_name(field_name) Sets a watch point for the specified table field in the specified stream. This formats scope is the current DML form. Therefore, its effect is terminated if the given form exits.

Examples
SET BREAK %LINE 15 SET BREAK INVOICE_ENTRY SET WATCH #part_numbers(23) SET WATCH TRANS:RENTALS(CUSTOMER_ID)

D-18

Interactive Debugger For DML Code IAF 8.0 DML

SHOW

SHOW
Syntax
SHOW keyword

Description
This command displays the settings of various debugger options.

Keywords
The following table lists and describes the keywords that are valid for use with the SHOW command. Keyword BREAK CALLS Description This keyword displays all currently set break points. This keyword displays the call path to the current location in the code (for example; a list of PERFORM statements that executed to reach the location). This keyword displays the current screen mode. This keyword displays the source file specification for the current form. This keyword displays all currently set watch points.

MODE SOURCE WATCH

Interactive Debugger For DML Code IAF 8.0 DML

D-19

STEP

STEP
Syntax
STEP [/qualifier] STEP nn

Description
This command causes the debugger to execute source code in the current form. Upon completing the given execution, the debugger returns control to its command line. If the STEP command specifies a value indicating the number of lines to execute (nn in syntax above), the debugger executes that many lines of code before stopping to await further instructions. Otherwise, if a qualifier is present, it determines the amount of code that the debugger executes. If no qualifier is present, the debugger uses an implicit /OVER qualifier.

Qualifiers
You can append one of the following qualifiers to the STEP command:

/BRANCH
This qualifier causes the debugger to execute the current form up to its next IF, GOTO, or END_FORM statement before stopping to await further instructions.

/CALL
This command causes the debugger to execute the current form up to its next PERFORM, CALL, or END_FORM statement before stopping to await further instructions.

D-20

Interactive Debugger For DML Code IAF 8.0 DML

STEP

/INTO
This qualifier causes the debugger to execute the next line of DML code in the current form (or a line of trigger code if applicable). If the given line of code is a PERFORM statement, this qualifier causes the debugger to stop and await further instructions at the first line of the called form. By default, the debugger executes the called form completely and stops to await further instructions only at the line of code following the PERFORM statement in the calling form (the default behavior). This qualifier overrides that behavior.

/OVER
This qualifier causes the debugger to execute the next line of DML code in the current form. If the given line of code is a PERFORM statement, this qualifier causes the debugger to execute the called form completely and to stop to await further instructions only at the line of code following the PERFORM statement in the calling form. This is the default behavior (for example; a STEP command without a qualifier behaves the same as a STEP/OVER command).

/RETURN
This qualifier causes the debugger to execute the current form up to its next EXIT or END_FORM statement before stopping to await further instructions.

Interactive Debugger For DML Code IAF 8.0 DML

D-21

TYPE

TYPE
Syntax
TYPE nnn

Description
If the debugger source code window is currently enabled (see the description of the SET MODE SCREEN debug command), this command causes the source code window to display the given line and the lines that surround it.

Example
TYPE 22

D-22

Interactive Debugger For DML Code IAF 8.0 DML

Appendix E

DML File Information

Introduction

Introduction
This appendix provides information regarding files associated with the Data Manipulation Language (DML.)

Limitations
IAF imposes some limits on the size and contents of any given single DML source file. Any elements that this appendix does not explicitly mention are limited only by the amount of available virtual memory.

DML File Limitations

Constraint Number of source lines Maximum 65535 Comments This is a DML debugger restriction only. IAF will compile and execute files that are larger than this. Referencing the same table field in two or more places still counts as only one table field. For details regarding forms, refer to this manuals Forms and Form Qualifiers chapter. For details regarding the EXTERNAL statement, refer to this manuals Language Statements chapter. To minimize the effect of this restriction, use /TOTAL=nn to reuse an accumulator, where nn is the number (1-100) of the accumulator to reuse.

Number of different table fields

4096

Number of forms per file

300

Number of EXTERNAL statements

80

Number of output blocks having a /TOTAL qualifier

100

E-2

DML File Information IAF 8.0 DML

Limitations

Constraint Number of streams using /STATISTIC qualifiers

Maximum 20

Comments For details regarding the /STATISTIC qualifier, refer to this manuals Forms and Form Qualifiers chapter.

DML File Information IAF 8.0 DML

E-3

DML Form Limitations

DML Form Limitations

Constraint Number of /BREAK qualifiers on a form header Maximum 20 Comments For details regarding the /BREAK qualifier, refer to this manuals Forms and Form Qualifiers chapter. Note that when using the AMONG operator with the /WITH qualifier each item in the specified among list counts as one /WITH qualifier. For details regarding the /WITH qualifier, refer to this manuals Forms and Form Qualifiers chapter. If the task at hand requires more than this number of INPUT blocks, split the given form into multiple forms.

Number of /WITH qualifiers on a form header

230

Number of INPUT blocks in a form

100

DML Statement Limitations

Constraint Number of arguments on a PERFORM, SWITCH, or CALL statement Maximu m 255 Comments For details regarding the PERFORM, SWITCH, and CALL statements, refer to this manuals Language Statements chapter. For details regarding IF and WHILE constructs, refer to this manuals Language Statements chapter. For details regarding the /STATISTIC qualifier, refer to this manuals Forms and Form Qualifiers chapter.

Number of IF and WHILE nesting levels

50

Number of /STATISTIC qualifiers per stream

40

E-4

DML File Information IAF 8.0 DML

Portable DMC Files

Portable DMC Files

Compiled DML files (for example; .dmc files) are portable. This means that a .dmc file created on a system having big endian architecture is executable on a system having little endian architecture, and vice versa. A system having big endian architecture is one on which data element addresses point to the datas most significant byte. A system having little endian architecture is one on which data element addresses point to the datas least significant byte. Big endian systems include the HP-3000 and HP-9000, the IBM RS6000, and PowerPC workstations. Little endian systems include those in the Digital VAX and AXP families and those in the Intel X86 family.

DML File Information IAF 8.0 DML

E-5

Appendix F

Electronic Signature and Audit Record

Introduction

Introduction
IAF contains functionality to capture a single or double electronic signature. It can also provide an audit record of the users and of the activity performed during the transaction which involves the capture of the electronic signature(s). This functionality permits IAF customers to comply with 21 CFR Part 11 Electronic Signature requirements, as mandated by the Food and Drug Administration. The electronic signature validation is initiated within a DML program by use of either a SIGNATURE_BLOCK for an interactive signature or a SIGNATURE statement for a non-interactive signature. Please refer to the SIGNATURE_BLOCK section of the Blocks and Block qualifiers chapter of this manual for detailed information concerning DML language qualifier and syntax information for the SIGNATURE_BLOCK. Please refer to the SIGNATURE section of the Language Statements chapter of this manual for detailed information concerning DML language qualifier and syntax information for the SIGNATURE statement.

Electronic Signature Validation Forms

Both the SIGNATURE_BLOCK and the SIGNATURE statement accept the /VALIDATION_FORM qualifier. The optional validation form is called before the usernames and passwords are authenticated by the operating system. This can be particularly useful when processing double electronic signatures, as it can be used to validate the relationship between username-1 and username-2. The validation form is passed nine text string parameters, in the following order:
type,purpose,username-1,username-2,user-defined-1,user-defined2,user-defined-3,user-defined-4,user-defined-5

The type (first) parameter contains a string literal, either SINGLE or DOUBLE to reflect the signature(s) being processed. When type is SINGLE, username-2 is a null string. Modifications made to the type parameter are always discarded after the validation form exits. The purpose (second) parameter contains the purpose, either the purpose as specified by the SIGNATURE_BLOCK or SIGNATURE statement /

F-2

Electronic Signature and Audit Record IAF 8.0 DML

Electronic Signature Validation Forms

PURPOSE qualifier, or in the case of a SIGNATURE_BLOCK only, the purpose as entered by the user. The validation form can modify the purpose parameter. In the case of a SIGNATURE_BLOCK only, the resulting new value is returned as the target of the /PURPOSE qualifier. Modifications made to the purpose parameter are also recorded in the audit file, if any. The username-1 (third) parameter always contains a value. In the case of a SIGNATURE_BLOCK, this is the first username as entered by the user. In the case of a SIGNATURE statement, this is the username as specified with the /USERNAME1 qualifier. The username-2 (fourth) parameter contains the username as entered by the user in the case of a SIGNATURE_BLOCK statement. In the case of a SIGNATURE statement, username-2 contains the username as specified with the /USERNAME2 qualifier. Username-2 is passed to the validation form as a null (empty) string whenever type is passed as SINGLE. Modifications to username-1 and username-2 are discarded after the validation form exits. The User-defined-1 (fifth) through user-defined-5 (ninth) parameters correspond to the values specified in any /USER1 through /USER5 qualifiers on the SIGNATURE_BLOCK or SIGNATURE statement. Modifications made to the user-defined-1 through user-defined-5 parameters within the validation form cause these parameters to be recorded in the audit file, if any, with their modified rather than original values. The validation form is responsible for displaying its own error messages and should use the ERROR/TEXT_ONLY statement for this purpose. The validation form should be coded to exit with a status of %SUCCESS if the relationship between username-1 and username-2 is valid and %FAILURE if the relationship is not valid. Alternatively, the form may be coded to exit with a status of %BACK or %EXIT. (See the sections on SIGNATURE_BLOCK and SIGNATURE for details about how this status will be handled.)

Electronic Signature and Audit Record IAF 8.0 DML

F-3

GEM_SIGNATURE_AUDIT_MODE System Custimization Variable (SCV)

GEM_SIGNATURE_AUDIT_MODE System Custimization Variable (SCV)

The GEM_SIGNATURE_AUDIT_MODE SCV is settable to TABLE, FILE or BOTH. This SCV was added for IAF V7.1. Setting this SCV to TABLE causes the signature audit to be written ONLY to the GEM_SIGNATURE_AUDIT table; setting it to FILE causes the signature audit to be written ONLY to the signature audit file; setting it to BOTH causes the signature audit to be written to both. The default is BOTH.

GEM_SIGNATURE_DEFAULT_ USERNAMES SCV

Starting with IAF V7.1, the GEM_SIGNATURE_DEFAULT_USERNAMES SCV may be used to provide defaults for the username fields within SIGNATURE_BLOCK dialogs. The GEM_SIGNATURE_DEFAULT_USERNAMES SCV has the following syntax:
keyword=value, keyword=value,

Where the valid keywords are: 1. DEFAULT1=

Set the default for username1. 2. DEFAULT2=

Set the default for username2. And the valid values are: 1. %LAST

a. When used with the DEFAULT2 keyword, default the corresponding username to the last corresponding username entered by the user.

F-4

Electronic Signature and Audit Record IAF 8.0 DML

GEM_SIGNATURE_DEFAULT_ USERNAMES SCV

b. When used with the DEFAULT1 keyword, default the corresponding username to the last corresponding username entered by the user. If the user has not previously entered a value for the corresponding username, then default the corresponding username to the current users username (i.e., if %LAST would be null, then the default becomes %USERNAME instead). 2. %NULL

Do not default the corresponding username. 3. %USERNAME

Default the corresponding username to the current users username. If a particular keyword is not specified, the default for that username is null. For instance, if DEFAULT2 is not specified, then the second username defaults to null (no default). Spaces, tabs and upper vs. lower case within the SCV content are all irrelevant. The default username values as specified with this SCV are only used if and when a signature form is displayed and the user is prompted to enter values. Example:
GEM_SIGNATURE_DEFAULT_USERNAMES=DEFAULT1=%LAST

Electronic Signature and Audit Record IAF 8.0 DML

F-5

Electronic Signature Audit Table

Electronic Signature Audit Table

The IAF V7.1 database upgrade adds a table called GEM_SIGNATURE_AUDIT to all IAF databases. This table is used by IAF to audit all electronic signature events. Whenever an electronic signature authentication is performed, an audit record is optionally written to the GEM_SIGNATURE_AUDIT table in either the default database or the specific database as specified with the SIGNATURE_BLOCK or SIGNATURE statement /HANDLE qualifier. However, this does not occur if an explicit /NOAUDIT qualifier was also specified. The record is written as soon as the authentication check has been completed, regardless of whether it succeeds or fails. If a SIGNATURE_BLOCK is used, authentication failure results in a failure audit record being written to the GEM_SINGATURE_AUDIT table before any subsequent action is taken (e.g. before user is prompted to re-enter the data values). Multiple audit records may therefore be generated from the execution of a single SIGNATURE_BLOCK. The GEM_SIGNATURE_AUDIT table contains the following tablefields:

(Sheet 1 of 2)

1. GEM_TRANSACTION_ID 2. GEM_DATE_TIME 3. GEM_SYSTEM_NAME 4. GEM_FACILITY_NAME 5. GEM_SIGNATURE_STATUS 6. GEM_SIGNATURE_PURPOSE 7. GEM_SIGNATURE_USERNAME1 8. GEM_SIGNATURE_USERNAME2 9. GEM_SIGNATURE_USER1 10. GEM_SIGNATURE_USER2

(TEXT, length 64) (DATE-TIME) (TEXT, length 31) (TEXT, length 31) (TEXT, length 32) (DOCUMENTARY) (TEXT, length 256) (TEXT, length 256) (DOCUMENTARY) (DOCUMENTARY)

F-6

Electronic Signature and Audit Record IAF 8.0 DML

Electronic Signature Audit Table

(Sheet 2 of 2)

11. GEM_SIGNATURE_USER3 12. GEM_SIGNATURE_USER4 13. GEM_SIGNATURE_USER5

(DOCUMENTARY) (DOCUMENTARY) (DOCUMENTARY)

The GEM_TRANSACTION_ID table-field contains the transaction identifier for the transaction that was active at the time the signature operation was performed, unless transaction identifier generation is disabled with the GEM_TRANSACTION_ID SCV. Please see Appendix G, IAF Transaction Identifiers for more information. The GEM_DATE_TIME table-field contains the date/time at which the electronic signature authentication took place. The GEM_SYSTEM_NAME and GEM_FACILITY_NAME tablefields contain the system name and facility name respectively of the facility that was executing at the time the signature operation was performed. The GEM_SIGNATURE_STATUS table-field contains either SUCCESS or FAILURE to indicate the status of the electronic signature process. The GEM_SIGNATURE_PURPOSE table-field contains the purpose of signing as specified by the program in the case of a SIGNATURE statement or as entered by the user in the case of a SIGNATURE_BLOCK statement. The GEM_SIGNATURE_USERNAME1 and GEM_SIGNATURE_USENAME2 table-fields contain the operating system usernames specified by the program in the case of a SIGNATURE statement or entered by the user in the case of a SIGNATURE_BLOCK statement. The GEM_SIGNATURE_USER1 through GEM_SIGNATURE_USER5 table-fields contains the five userdefined values as specified by the SIGNATURE_BLOCK or SIGNATURE statements /USER1 through /USER5 qualifiers.

Electronic Signature and Audit Record IAF 8.0 DML

F-7

Electronic Signature Audit File

Electronic Signature Audit File

Prior to IAF V7.1 electronic signature events could only be audited to an audit file on disk. Even though the GEM_SIGNATURE_AUDIT table has since been added to all IAF databases by the IAF V7.1 database upgrade, this audit log file feature not only continues to exist and be supported, but has also been enhanced to include all of the same information as is present in the GEM_SIGNATURE_AUDIT table. Whenever an electronic signature authentication is performed, an audit record is optionally written to an ASCII format electronic signature audit file, unless an explicit /NOAUDIT has been specified on the relevant SIGNATURE_BLOCK or SIGNATURE statement. The record is written as soon as the authentication check has been completed, regardless of whether it succeeds or fails. If a SIGNATURE_BLOCK is used, authentication failure results in a failure audit record being written to the log file before any subsequent action is taken (e.g. before user is prompted to re-enter the data values). Multiple audit records may therefore be generated from the execution of a single SIGNATURE_BLOCK. On the OpenVMS platform the default audit log file is gem_root:[log]gem_signature_audit.log. On UNIX platforms the default audit log file is $GEM_ROOT/log/ gem_signature_audit.log. On Windows platforms the default audit log file is root\log\gem_signature_audit.log where root is the location where you installed IAF. On all platforms, the default name and location of the audit file can be overridden with the GEM_SIGNATURE_AUDIT_FILE SCV. Both the default file specification and any GEM_SIGNATURE_AUDIT_FILE SCV definition can be overridden with the /AUDIT qualifier of individual SIGNATURE_BLOCK and SIGNATURE statements. Any explicit directory or filename specified in the SCV will override the default directory and filename. Also, any explicit directory or filename specified in the /AUDIT qualifier will override those parts of the SCV and default values.

F-8

Electronic Signature and Audit Record IAF 8.0 DML

Electronic Signature Audit File

Open VMS Examples

Condition No GEM_SIGNATURE_AUDIT_FILE SCV defined and no /AUDIT qualifier No SCV but /AUDIT=LOCAL_SIG

Audit File Information Audit file is GEM_ROOT:[LOG]GEM_SIGNATURE_AUDIT.LOG Audit file is GEM_ROOT:[LOG]LOCAL_SIG.LOG

No SCV but / Audit file is USER$JENS:[SIG]TEST.SIG AUDIT=USER$JENS:[SIG]TEST.SIG SCV is USER$THOM:[DB] and no / AUDIT qualfier SCV is USER$THOM:[DB] and / AUDIT=LOCAL_TEST SCV is USER$THOM:[DB]AUDIT_SIG.TXT and /AUDIT=LOCAL_TEST Audit file is USER$THOM:[DB]GEM_SIGNATURE_AUDIT.LOG Audit file is USER$THOM:[DB]LOCAL_TEST.LOG Audit file is USER$THOM:[DB]LOCAL_TEST.TXT

Note: If the audit log file is to be shared between multiple users, the default security settings on the file may have to be amended to grant access. The ASCII format audit record contains the following information: The date/time at which the electronic signature authentication took place. The date/time is written in standard DD-MON-YYYY HH:MM:SS.HH format. The transaction identifier for the transaction that was active at the time the signature operation was performed, unless transaction identifier generation is disabled with the GEM_TRANSACTION_ID SCV. Please see Appendix G, IAF Transaction Identifiers for more information. The system name and facility name of the facility that was executing at the time the signature operation was performed. The operating system username or usernames specified by the program in the case of a SIGNATURE statement or entered by the user in the case of a SIGNATURE_BLOCK statement. The SUCCESS or FAILURE status of the electronic signature process.

Electronic Signature and Audit Record IAF 8.0 DML

F-9

Signature Identifiers

The purpose of signing as specified by the program in the case of a SIGNATURE statement or as entered by the user in the case of a SIGNATURE_BLOCK statement. The five user-defined values as specified by the /USER1 through / USER5 qualifiers. The above information is written in variable length, comma-separated, tagged format. Each field contains a tag name and an equals sign, followed by the field data in quotes. Null fields are omitted altogether. For example:
DATETIME=1-SEP-2004 01:02:03.04,USERNAME1=username1, USERNAME2=username2,STATUS=SUCCESS,PURPOSE=purpose, USER1=user-defined-1,USER2=user-defined-2, USER3=user-defined-3,USER4=user-defined-4,USER5=user-defined-5

Note: The text above would all be one line in the audit file. Due to page size constraints, the text above is broken by line. This appears as one line in the audit log file. Due to operating system and IAF internal limitations respectively, the maximum length of the ASCII text file audit record is 32,767 bytes on the OpenVMS platform and 65,535 bytes on all other platforms. If this maximum length is exceeded, some fields will be truncated or dropped entirely. First, user-defined-5 will be truncated to fit in the available space. If the record length is still above the limit, then user-defined-5 is dropped. If the record length is still above the limit, then user-defined-4 is truncated or dropped as necessary. This proceeds with user-defined-3, user-defined-2, user-defined-1 and then finally purpose until the record length drops below the limit.

Signature Identifiers
Signature identifiers are similar to transaction identifiers. A signature identifier is generated and %SIGNATURE_ID is set each time a signature statement or signature_block is successfully executed. From that point on until the next signature_block or signature statement, all GEM_SIGNATURE_ID table-fields are populated with the signature identifier. Once %SIGNATURE_ID is set with a successful SIGNATURE_BLOCK or SIGNATURE statement SIGNATURE/ERASE (with no other qualifiers) can be used to set %SIGNATURE_ID back to a null value.

F-10

Electronic Signature and Audit Record IAF 8.0 DML

Appendix G

IAF Transaction Identifiers

Introduction

Introduction
Starting with IAF V7.1, whenever IAF starts a transaction, it generates a 64 character globally unique transaction identifier. The transaction identifier is available to application developers in two separate ways. First via the %GTID special variable and second via a special read-only tablefield named GEM_TRANSACTION_ID.

Transaction Identifiers
The %GTID special variable contains the IAF transaction identifier only while a transaction is active. The value changes each time the transaction level, as indicated by the %TRANS_LEVEL special variable, transitions from zero to one and from one to zero. It does not change as the transaction level increases beyond one (pseudo transactions). %GTID has a null value () when no transaction is active. GEM_TRANSACTION_ID is a global field, data-type TEXT, length 64 characters, uppercase only. Whenever the special GEM_TRANSACTION_ID table-field is present in a table, it is automatically updated by IAF (automatically without programmer intervention of any kind) to contain the transaction identifier of the currently active transaction. All GEM_TRANSACTION_ID table-fields are implicitly read-only and cannot be altered programmatically except by making a modification to any table-field in the record. Any time a record is added or updated, any existing the transaction identifier value in the GEM_TRANSACTION_ID field contained within the record in question is updated to reflect the transaction identifier of the transaction that was active at the time the update took place. Usage of GEM_TRANSACTION_ID table-fields is not restricted to user tables. The GEM_DATA_AUDIT and GEM_SIGNATURE_AUDIT tables are examples of IAF tables that contain GEM_TRANSACTION_ID table-fields. The ARCHIVE, EXPORT, and IMPORT statements are an exception to the rule in regards to GEM_TRANSACTION_ID table-fields. All three of the statements transfer data from one database to another (or from a CSV file to a table in the case of IMPORT/CSV) without changing the value of the GEM_TRANSACTION_ID table-field. The value in the destination table records is always identical to the value of the source table records, even if existing records are updated in the process.
G-2 IAF Transaction Identifiers IAF 8.0 DML

Transaction Identifiers

Use either UTILITIES DDF TABLE ADD/MODIFY dialog or the DML ADD/MODIFY TABLE metadata statements to add GEM_TRANSACTION_ID table-fields to tables. Note that the name of the table-field itself must be GEM_TRANSACTION_ID for this feature to work. This feature intentionally does not operate with table-fields that are named using some other table-field name and then made to be based on the GEM_TRANSACTION_ID global field. The GEM_TRANSACTION_ID SCV is a standard IAF true/false SCV. This SCV can be set to a FALSE value to disable the global transaction identifier feature. The default setting for the GEM_TRANSACTION_ID SCV is TRUE. If this SCV is explicitly set to a FALSE value (thus disabling the feature), then: 1. 2. 3. The global transaction identifier is not generated when a transaction is started. The %GTID special variable is set to a null (i.e., ) value. Other than being treated as READ-ONLY table fields, GEM_TRANSACTION_ID fields receive no special treatment.

IAF Transaction Identifiers IAF 8.0 DML

G-3

Appendix H

IAF Transaction Archiving

Introduction

Introduction
Transaction Archiving offers a supportive framework for transferring data from one database into an identically-structured archive database. This permits DML report programs that run against the source database to also run against the archive database without modification. Master data (such as company codes, customer data) in an archive database is transferred from a production database to an archive database with the DML EXPORT and IMPORT statements. Transactional data is transferred with the ARCHIVE statement.

Archiving Phases
Archiving of transactional data comprises two phases: 1. Marking rows for archive. In this phase, individual table rows are marked as being ready for archive using the MARK statement. Multiple rows on multiple tables may be involved in this phase. There is no requirement to mark all affected rows in a single run. No data transfer is done during this phase. Transfer of archive data. In this phase, data is physically transferred from the source database to the target database (e.g. from a production to an archive database) using the ARCHIVE statement. All tables are checked and all rows marked for archive are transferred. The transfer is verified and, if successful, the archived records are then deleted from the source tables in the original database. The metadata relating to all tables involved in the transfer must be identical in the source and target databases. This ensures that the transfer is both reversible and that archived material can be moved back into the original source database.

2.

Before any rows in a table can be marked for archive, the table itself must support archiving. Whether or not the rows in a table can be archived is specified for an individual table when it is created, either in UTILTIES DDF TABLE ADD or with the metadata definition language statements ADD TABLE table_name /ARCHIVE or ADD TABLE table_name / NOARCHIVE. By default, all tables are created with no support for archiving. Existing tables can also be modified to add or remove archiving support with either UTILITIES DDF TABLE MODIFY or with the metadata definition language statements MODIFY TABLE

H-2

IAF Transaction Archiving IAF 8.0 DML

Archiving Phases

table_name /ARCHIVE or MODIFY TABLE table_name / NOARCHIVE. DML programs use the MARK statement to mark the current row in the specified table for archiving. All marked rows will be transferred to the archive database on the next archiving run. The UNMARK statement is used to reverse that setting and ensure that the record will not be transferred in the next archiving run. An error message is generated if the record in question is currently involved in an on-going archiving session. DML programs can check if the current record on a given table has been marked for archive by using the IS_MARKED() and IS_MARKED_ON_STREAM() functions. Programs can also use the TABLE_ARCHIVABLE() function to determine if a given table supports archiving. The physical archiving process itself is triggered by the use of the ARCHIVE statement. If there is an incomplete archive session still in progress, IAF generates an error message. Any existing session must be completed before another can be started. When the /VERIFY qualifier is specified, an additional check is carried out on source and target tables to ensure that the correct number of rows have been transferred. The metadata audit table records information about any archiving sessions. Audit entries are made to signify the start and end of the transfer phase during which rows marked for archive are copied across to the target database. Audit entries are also made to signify the start and end of the delete phase, when the transferred rows are removed from the source database. In the event of a failure during the archiving process, any restart of the procedure is also audited. The GEM_ARCHIVE_LOG table is used to record information about an archiving session. This table is updated as the archive progresses. When a session has completed successfully, all relevant entries are deleted from this table. In the event that the archive session fails, the contents of this table can be used by IAF to recover and complete the archiving process. When a row in a table is marked for archive, the mark consists of a certain value being set in the GEM_ARCHIVE_FLAG table-field within the row. This table-field is also modified when rows are unmarked and during the time an archiving session is in progress. All GEM_ARCHIVE_FLAG table-fields are READ-ONLY within IAF. You must not attempt to modify them (inside or outside of IAF) except via the official ARCHIVE, MARK and UNMARK statement mechanisms. GEM_ARCHIVE_FLAG

IAF Transaction Archiving IAF 8.0 DML

H-3

Archiving Phases

table-fields are user visible in such locations as TED and QBF for your convenience. (They are not visible in UTILITIES DDF.) DO NOT become dependent upon the values which you may see in GEM_ARCHIVE_FLAG table-fields. DO NOT write programs of any sort that directly inspect the contents of these table-fields. Use only the official IS_MARKED() and IS_MARKED_ON_STREAM() mechanisms for inspecting their contents. Note: How these table-fields are used and what they contain when a row is marked is internal to IAF and is subject to change without notice.

H-4

IAF Transaction Archiving IAF 8.0 DML

Appendix I

IAF Character Set Conversion Support

Base Character Sets

Base Character Sets

IAF supports the following character set names for use with the GEM_CHARACTER_SET and GEM_DB_CHARSET SCVs: ANSI_X3.4-1986, CP367, IBM367, US, csASCII, ISO646.1991-IRV ARMSCII-8 ASCII, US-ASCII, ISO646-US, ISO_646.IRV:1991, ISO-IR-6, ANSI_X3.4-1968 BIG5, BIG-5, BIG-FIVE, BIGFIVE, CN-BIG5, csBig5 BIG5-HKSCS C99 CP1046 CP1124 CP1125 CP1129 CP1133, IBM-CP1133 CP1161, IBM1161, IBM-1161, csIBM1161 CP1162, IBM1162, IBM-1162, csIBM1162 CP1163, IBM1163, IBM-1163, csIBM1163 CP1250, WINDOWS-1250, MS-EE CP1251, WINDOWS-1251, MS-CYRL CP1252, WINDOWS-1252, MS-ANSI CP1253, WINDOWS-1253, MS-GREEK CP1254, WINDOWS-1254, MS-TURK CP1255, WINDOWS-1255, MS-HEBR

I-2

IAF Character Set Conversion Support IAF 8.0 DML

Base Character Sets

CP1256, WINDOWS-1256, MS-ARAB CP1257, WINDOWS-1257, WINBALTRIM CP1258, WINDOWS-1258 CP437, IBM437, 437, csPC8CodePage437 CP737 CP775, IBM775, csPC775Baltic CP850, IBM850, 850, csPC850Multilingual CP852, IBM852, 852, csPCp852 CP853 CP855, IBM855, 855, csIBM855 CP856 CP857, IBM857, 857, csIBM857 CP858 CP860, IBM860, 860, csIBM860 CP861, IBM861, 861, CP-IS, csIBM861 CP862, IBM862, 862, csPC862LatinHebrew CP863, IBM863, 863, csIBM863 CP864, IBM864, csIBM864 CP865, IBM865, 865, csIBM865 CP866, IBM866, 866, csIBM866 CP869, IBM869, 869, CP-GR, csIBM869 CP874, WINDOWS-874 CP922 CP932

IAF Character Set Conversion Support IAF 8.0 DML

I-3

Base Character Sets

CP943 CP949, UHC CP950 DEC-HANYU DEC-KANJI EUC-CN, EUCCN, GB2312, CN-GB, csGB2312 EUC-JISX0213 EUC-JP, EUCJP, Extended_UNIX_Code_Packed_Format_for_Japanese, csEUCPkdFmtJapanese EUC-KR, EUCKR, csEUCKR EUC-TW, EUCTW, csEUCTW GB18030 GBK, CP936 GB_1988-80, ISO646-CN, ISO-IR-57, CN, csISO57GB1988 GB_2312-80, ISO-IR-58, csISO58GB231280, CHINESE GEORGIAN-ACADEMY GEORGIAN-PS HANGUL, HANYU, HANZI, HP-ROMAN8, ROMAN8, R8, csHPRoman8 HZ, HZ-GB-2312 ISO-2022-CN, csISO2022CN ISO-2022-CN-EXT ISO-2022-JP, csISO2022JP
I-4 IAF Character Set Conversion Support IAF 8.0 DML

Base Character Sets

ISO-2022-JP-1 ISO-2022-JP-2, csISO2022JP2 ISO-2022-JP-3 ISO-2022-KR, csISO2022KR ISO-8859-1, ISO_8859-1, ISO_8859-1:1987, ISO-IR-100, CP819, IBM819, LATIN1, L1, csISOLatin1 ISO-8859-10, ISO_8859-10, ISO_8859-10:1992, ISO-IR-157, LATIN6, L6, csISOLatin6 ISO-8859-13, ISO_8859-13, ISO-IR-179, LATIN7, L7 ISO-8859-14, ISO_8859-14, ISO_8859-14:1998, ISO-IR-199, LATIN8, L8, ISO-CELTIC ISO-8859-15, ISO_8859-15, ISO_8859-15:1998, ISO-IR-203 ISO-8859-16, ISO_8859-16, ISO_8859-16:2000, ISO-IR-226 ISO-8859-2, ISO_8859-2, ISO_8859-2:1987, ISO-IR-101, LATIN2, L2, csISOLatin2 ISO-8859-3, ISO_8859-3, ISO_8859-3:1988, ISO-IR-109, LATIN3, L3, csISOLatin3 ISO-8859-4, ISO_8859-4, ISO_8859-4:1988, ISO-IR-110, LATIN4, L4, csISOLatin4 ISO-8859-5, ISO_8859-5, ISO_8859-5:1988, ISO-IR-144, CYRILLIC, csISOLatinCyrillic ISO-8859-6, ISO_8859-6, ISO_8859-6:1987, ISO-IR-127, ECMA-114, ASMO-708, ARABIC, csISOLatinArabic ISO-8859-7, ISO_8859-7, ISO_8859-7:1987, ISO-IR-126, CMA-118, ELOT_928, GREEK8, GREEK, csISOLatinGreek ISO-8859-8, ISO_8859-8, ISO_8859-8:1988, ISO-IR-138, HEBREW, csISOLatinHebrew ISO-8859-9, ISO_8859-9, ISO_8859-9:1989, ISO-IR-148, LATIN5, L5, csISOLatin5

IAF Character Set Conversion Support IAF 8.0 DML

I-5

Base Character Sets

ISO-IR-165, CN-GB-ISOIR165 JAVA JIS_C6220-1969-RO, ISO646-JP, ISO-IR-14, JP, csISO14JISC6220ro JIS_X0201, JISX0201-1976, X0201, csHalfWidthKatakana JIS_X0208, JIS_X0208-1983, JIS_X0208-1990, JIS0208, X0208, ISOIR-87, JIS_C6226-1983, csISO87JISX0208 JIS_X0212, JIS_X0212.1990-0, JIS_X0212-1990, X0212, ISO-IR-159, csISO159JISX02121990 JOHAB, CP1361 KANJI (RESERVED TO YIC) KANJI_SJIS (RESERVED TO YIC) KOI8-R, csKOI8R KOI8-RU KOI8-T KOI8-U KSC_5601, KS_C_5601-1987, KS_C_5601-1989, ISO-IR-149, csKSC56011987, KOREAN MULELAO-1 RISCOS-LATIN1 SHIFT_JIS, SHIFT-JIS, SJIS, MS_KANJI, csShiftJIS SHIFT_JISX0213 TCVN, TCVN-5712, TCVN5712-1, TCVN5712-1:1993 TDS565 TIS-620, TIS620, TIS620-0, TIS620.2529-1, TIS620.2533-0, TIS620.2533-1, ISO-IR-166 VISCII, VISCII1.1-1, csVISCII

I-6

IAF Character Set Conversion Support IAF 8.0 DML

Additional Character Sets

Additional Character Sets

In addition to the above character set names, the following additional character sets are supported for use with the translate function, but are not supported for use with the GEM_CHARACTER_SET and GEM_DB_CHARSET SCVs UCS-2, ISO-10646-UCS-2, csUnicode UCS-2-INTERNAL UCS-2-SWAPPED UCS-2BE, UNICODEBIG, UNICODE-1-1, csUnicode11, UCS-2LE, UNICODELITTLE UCS-4, ISO-10646-UCS-4, csUCS4 UCS-4-INTERNAL UCS-4-SWAPPED UCS-4BE UCS-4LE UTF-16 UTF-16BE UTF-16LE UTF-32 UTF-32BE UTF-32LE UTF-7, UNICODE-1-1-UTF-7, csUnicode11UTF7 UTF-8

IAF Character Set Conversion Support IAF 8.0 DML

I-7

Appendix J

IAF PDF Reports and PDF File Production

Introduction

Introduction
Both IAF REPORT_FORMs and text files opened with the OPEN_TEXT/CREATE statement can be made to produce PDF files instead of the traditional listing file format. In both cases this is done using the /PDF qualifier. IAF has two methods for creating PDF report files. Method one uses IAFs own built-in PDF production facility. Method two uses a third party product called PDFlib (see http://www.pdflib.com), which requires a license from PDFlib GmbH. The IAF PDF library does not implement the entire PDF specification. The library has certain limitations that are discussed later in this section. The IAF PDF library is intended to be a very light PDF generation utility that provides simple PDF report generation as an alternative to the .lis format. For full PDF production capability, it is recommended to use the PDFlib. By default, IAF determines which method to use, to generate PDF report files. IAF uses PDFlib if any of the following are true: A font name other than Courier, Courier-Bold, Courier-Oblique, Courier-BoldOblique, Helvetica, Helvetica-Bold, HelveticaOblique, Helvetica-BoldOblique, Times-Roman, Times-Bold, Times-Italic, Times-BoldItalic, Symbol, ZapfDingbats, STSongLight, STSongStd-Light-Acro, AdobeSongStd-Light-Acro, MHeiMedium, MSung-Light, MSungStd-Light-Acro, AdobeMingStdLight-Acro, HeiseiKakuGo-W5, HeiseiMin-W3, KozMinProRegular-Acro, KozGoPro-Medium-Acro, HYGoThic-Medium, HYSMyeongJo-Medium, HYSMyeongJoStd- Medium-Acro or AdobeMyungjoStd-Medium-Acro is specified. The GEM_PDFLIB_LICENSE SCV is set to a non-null value. The GEM_PDFLIB_LICENSEFILE SCV is set to a non-null value. GEM_CHARACTER_SET=UTF-8 (See comments below regarding specifying a PDF character set to override this behavior) IAFs own internal PDF production code supports GEM_CHARACTER_SET single byte encodings used with Adobe Core (Latin) fonts, as well as GEM_CHARACTER_SET CJK encodings with Adobe Standard CJK fonts. Setting GEM_CHARACTER_SET=UTF-8

J-2

IAF PDF Reports and PDF File Production IAF 8.0 DML

Introduction

causes PDFlib to be used, as this is the recommended method for PDF production with UTF-8. However, you can override this and use the built-in IAF production method with UTF-8, as described in the following sections. Note that IAF can be forced to use a specific production method with the GEM_PDF_LIBRARY SCV. Valid values for this SCV are: PDFLIB, IAF, and CONDITIONAL (the default). When PDFlib is used without a license, PDFlib places a demo mode watermark diagonally across each page. To remove this watermark, you need to purchase a PDFlib license from http://www.pdflib.com and supply it to PDFlib by setting either the GEM_PDFLIB_LICENSE or GEM_PDFLIB_LICENSEFILE SCV. On UNIX platforms, PDFlib is linked into IAF. On the OpenVMS platform, PDFlib is contained in a separate image that can be shared. On the Windows platform, PDFlib is contained in a separate dynamic link library. The GEM_PDFLIB_LIBRARY SCV can be used to override this and to use the specified image, dynamic link library, or shared library. This is true even on UNIX platforms.

Font Usage
When using Adobe Core fonts, you must not specify Glyphs that are not contained in the font when defining the PDF entities. IAF assigns the correct Glyph name and encoding, but a Glyph will not be displayed or printed correctly if the specified font doesnt contain that Glyph. When needed, IAF includes both an encoding dictionary and a TO_UNICODE table in the PDF files. PDFlib must be used whenever support for other fonts and encodings is required. Note that Arial is not an Adobe Core font, and use of Arial will force IAF to use PDFlib for PDF production. This is true for any non Adobe Core font, but Arial is a common Microsoft font that is commonly used on Windows platforms.

IAF PDF Reports and PDF File Production IAF 8.0 DML

J-3

Introduction

Single-Byte Character Set Usage

For single-byte character sets, IAF normally attempts the PDF production itself, and PDFlib will not be used. For example, with GEM_CHARACTER_SET=ISO-8859-1, IAF can produce PDF files containing Spanish language characters. With GEM_CHARACTER_SET=ISO-8859-4, IAF can produce PDF files containing, for example, Lithuanian language characters. It is assumed that you are using one of the Adobe Core Fonts, for example, Helvetica. Using Arial forces the use of PDFlib. You can also force the use of PDFlib with single-byte character sets by setting GEM_PDF_LIBRARY=PDFLIB. The following table summarizes Spanish language PDF production (assuming an Adobe Core Font): GEM_CHARACTER_SET ISO-8859-1 ISO-8859-1 ISO-8859-1 GEM_PDF_LIBRARY CONDITIONAL (default) IAF PDFLIB RESULT IAF used IAF used PDFlib used

The following table summarizes Lithuanian language PDF production (assuming an Adobe Core Font): GEM_CHARACTER_SET ISO-8859-4 ISO-8859-4 ISO-8859-4 GEM_PDF_LIBRARY CONDITIONAL (default) IAF PDFLIB RESULT IAF used IAF used PDFlib used

The tables for the other single-byte character sets are similar to the above.

J-4

IAF PDF Reports and PDF File Production IAF 8.0 DML

Introduction

CJK Usage
For Chinese, Japanese or Korean language character sets, IAF normally attempts the PDF production itself, and PDFlib is not used. For example, with GEM_CHARACTER_SET=KANJI_SJIS, IAF can produce PDF files containing Japanese language characters. Note that this assumes you are using one of the Adobe Standard CJK Fonts, for example, KozMinPro-Regular-Acro. Using a non-Adobe Standard CJK font forces the use of PDFlib. You can also force the use of PDFlib by setting GEM_PDF_LIBRARY=PDFLIB. The following table shows Japanese language PDF production (assuming an Adobe Standard CJK Font): GEM_CHARACTER_SET KANJI_SJIS KANJI_SJIS KANJI_SJIS GEM_PDF_LIBRARY CONDITIONAL (default) IAF PDFLIB RESULT IAF used IAF used PDFlib used

The tables for the other Chinese, Japanese and Korean characters sets are similar to the above.

Additional Notes for CJK Usage with PDFlib

When using PDFlib 7.0, a set of CMap resources are required for CJK output. This was not the case for PDFlib 6.0. These resources can be obtained and installed as follows: 1. 2. 3. Go to http://www.pdflib.com/download/resources/cmaps and download the CMaps zip or tar file. Follow the instructions at the website to unpack or install this into a suitable folder. If the folder is not installed in one of the standard places mentioned at the website, add the following SCV to point to the folder:

GEM_PDFLIB_SEARCHPATH=/<path to pdflib>/resource/cmap For example:

IAF PDF Reports and PDF File Production IAF 8.0 DML

J-5

Introduction

set_env=GEM_PDFLIB_SEARCHPATH=C:\PDFlib\resource\cmap

UTF-8 Usage
By default, when GEM_CHARACTER_SET=UTF-8, IAF defers to PDFlib for PDF production. PDFlib is the method used in this case as it is well suited to multiple language support with UTF-8. However, if you are using UTF-8 but you know that your data is fully included in a single encoding, such as English and/or Spanish - both ISO-8859-1, or Lithuanian in ISO-8859-4 for example, then you can force IAF PDF production by using the GEM_PDF_CHARSET SCV to specify the character set of your data. IAF will translate your data from UTF-8 to the single-byte character encoding specified by GEM_PDF_CHARSET before generating the PDF file. GEM_PDF_CHARSET should be used only when GEM_CHARACTER_SET=UTF-8 and IAFs built-in PDF production facility is being used. The following table shows UTF-8 PDF production (assuming an Adobe core font): GEM_CHARACTER_SET UTF-8 UTF-8 UTF-8 GEM_PDF_LIBRARY CONDITIONAL PDFLIB IAF GEM_PDF_CHARSET RESULT PDFlib used PDFlib used IAF used possible error** <single-byte charset>* IAF used ***

UTF-8

IAF

* Note: Replace <single-byte charset> with the character set of your data. For example, ISO-8859-4 for Lithuanian, ISO-8859-1 for Spanish, etc. **If you force IAF PDF usage without using GEM_PDF_CHARSET, a report will be generated if your data consists of single-byte UTF-8 characters only. For multi-byte UTF-8 characters, the PDF report generation will terminate with an error. This is not recommended usage, and is mentioned here for documentation purposes.

J-6

IAF PDF Reports and PDF File Production IAF 8.0 DML

Introduction

***When specifying a value for GEM_PDF_CHARSET, enure that you specify the correct value for your data. A valid PDF file will be produced as long as the data can be translated from UTF-8 to the character set specified by GEM_PDF_CHARSET. Otherwise, the PDF production will terminate with an error.

UTF-8 Usage and CJK

When using GEM_CHARACTER_SET=UTF-8, Chinese, Japanese and Korean language characters can be used with IAFs built-in PDF production as long as an Adobe Standard CJK Font is used. Using a font that is not an Adobe Standard CJK Font will require the use of PDFlib. GEM_PDF_CHARSET is not required here for IAF PDF production with CJK data, as long as you use an Adobe Standard CJK font. The following table summarizes UTF-8 and CJK usage: GEM_CHARACTER_SET UTF-8 GEM_PDF_LIBRARY CONDITIONAL FONT <Adobe Std CJK font> <other font> RESULT IAF used

UTF-8

CONDITIONAL

PDFlib used IAF used

UTF-8

IAF

<Adobe Std CJK font> *

UTF-8

PDFLIB

PDFlib used

*Note: PDFLIB can be used with an Adobe Standard CJK Font or another suitable Asian font.

IAF PDF Reports and PDF File Production IAF 8.0 DML

J-7

PDF Reports and PDF File Production

PDF Reports and PDF File Production

When a proportional font (or any font which IAF does not know for certain is a fixed width font) is used in a REPORT form, IAF trims spaces off left justified column text and attempts to align the text at absolute positions while permitting the text to flow proportionally between the columns. Text which has been right justified with an edit mask starting with the !- character sequence is space trimmed on the left and aligned to the right end of its respective column space. The dashes in the headings are also replaced with actual lines drawn on the page. The CELLSIZE option of the /PDF qualifier can be used to control the optimism/ pessimism of column positioning and column width calculations. The UTILITIES file manager searches for .PDF document files in addition to .LIS listing files when listing report files. However it can only display, edit, or print PDF files in GCWpro and thin client modes if a PDF viewer, such as Adobe Reader is installed on the Windows client machine. Adobe Reader can be used to display and/or print PDF files. It wont print them automatically. Once in Adobe Reader, you must select the Print menu item to print the PDF. Once in the print dialog, select fit to page. Also select landscape printing mode, if that is the page orientation of your report. PDF supports various security features which aid in protecting document contents. They are based on Acrobats standard encryption handler which uses symmetric encryption. Both Adobe Reader and the full Acrobat product support the following security features: * Permissions restrict certain actions for the PDF document, such as printing or extracting text. * The user password is required to open the file. * The owner password is required to change any security settings, i.e. permissions, user or owner password. Files with user and owner passwords can be opened for reading or printing with either password. Passwords can be set with the /PDF qualifiers OWNER_PASSWORD and USER_PASSWORD options. If a user password or permissions (see below), but no owner password has been supplied, then a regular user would be able to change the security settings. For this reason PDFlib considers this situation as an error.

J-8

IAF PDF Reports and PDF File Production IAF 8.0 DML

PDF Reports and PDF File Production

If the user and owner password are the same, a distinction between user and owner of the file would no longer be possible, again defeating effective protection. PDFlib considers this situation as an error. Up to a maximum of 32 characters will be used for both owner and user passwords. Additional characters will be ignored, and do not affect encryption. Empty passwords are not allowed. If a file has an owner or user password or any permission restrictions set, it will be encrypted. 128-bit encryption is used. This requires Acrobat 5 or above for all users of the document. Passwords should be at least six characters long and should contain nonalphabetic characters. Passwords should definitely not resemble your spouses or pets name, your birthday etc. in order to prevent so-called dictionary attacks or password guessing. It is important to mention that even with 128-bit encryption short passwords can be cracked within minutes. Attention must be paid when characters outside the range 0x20-0x7E are used in passwords, i.e. characters which are not in the traditional ASCII character set. As an example, lets take a look at the use of the character within a password. On the Mac this character has code 0x80, while on Windows it is encoded as 0xC4. Since users expect the file to be opened when using the password on either platform, Acrobat converts the supplied password to an internal encoding (called PDFDocEncoding) before applying the password. Characters which are not available in this encoding will be mapped to the space character. PDFDocEncoding contains all characters of the Mac and Windows platforms, but requires several characters to be converted. In the example above, when the user encrypts the file with password on the Mac, PDF readers would be unable to decrypt the file if the code for would be used directly. PDFlib therefore applies the same password conversion as Acrobat in order to make sure that files encrypted with Mac or Windows versions of Acrobat can successfully be decrypted. When encrypting files, PDFlib will act like Acrobat on Windows and interpret the supplied passwords in WinAnsi encoding, i.e., it will apply a WinAnsi to PDFDocEncoding conversion to the supplied user and master passwords. Setting some access restriction, such as printing prohibited will disable the respective function in Acrobat. However, this not necessarily holds true for third-party PDF viewers or other software. It is up to the developer of PDF tools whether or not access permissions will be honored. Indeed, several PDF tools are known to ignore permission settings altogether; commercially available PDF cracking tools can be
IAF PDF Reports and PDF File Production IAF 8.0 DML J-9

PDF Reports and PDF File Production

used to disable any access restrictions. This has nothing to do with cracking the encryption; there is simply no way that a PDF file can make sure it wont be printed while it still remains viewable. This is actually documented in Adobes own PDF reference: There is nothing inherent in PDF encryption that enforces the document permissions specified in the encryption dictionary. It is up to the implementers of PDF viewers to respect the intent of the document creator by restricting user access to an encrypted PDF file according to the permissions contained in the file. Whenever IAF uses PDFlib to produce the PDF file, IAF requests PDFlib to apply a process called linearization to PDF documents which it produces. Linearized PDF is called Optimized in Acrobat 4, and Fast Web View in Acrobat 5 and above. Linearization reorganizes the objects within a PDF file and adds supplemental information which can be used for faster access. (Please note that IAFs own internal PDF production facility does not support the production of linearized documents.) While non-linearized PDFs must be fully transferred to the client, a Web server can transfer linearized PDF documents one page at a time using a process called byte serving. It allows Acrobat (running as a browser plugin) to retrieve individual parts of a PDF document separately. The result is that the first page of the document will be presented to the user without having to wait for the full document to download from the server. This provides enhanced user experience. Note that the Web server streams PDF data to the browser, not IAF. Instead, IAF prepares the PDF files for byte serving. All of the following requirements must be met in order to take advantage of byte serving PDFs: * The Web server must support byte serving. The underlying byte range protocol is part of HTTP 1.1 and therefore implemented in all current Web servers. * The user must use Acrobat as a Browser plug-in, and have page-at-atime download enabled in Acrobat (Acrobat 6: Edit, Preferences, [General...,] Internet, Allow fast web view; Acrobat 5: Edit, Preferences, General..., Options, Allow Fast Web view). Note that this is enabled by default. The larger a PDF file (measured in pages or MB), the more it will benefit from linearization when delivered over the Web. Note: Linearizing a PDF document generally slightly increases its file size due to the additional linearization information.

J-10

IAF PDF Reports and PDF File Production IAF 8.0 DML

PDF Reports and PDF File Production

PDFlib must create the full document before it can be linearized; the linearization process will be applied in a separate step after the document has been created. For this reason PDFlib has additional storage requirements for linearization. Temporary file storage will be required which has roughly the same size as the generated document (without linearization).

PDF Reports and PDF File SCVs

The following SCVs can be used to control defaults: GEM_PDF_CHARSET This SCV can be used to specify the character set to be used by the IAF built-in PDF production code. It is only valid when GEM_CHARACTER_SET=UTF-8. The SCV directs IAF to convert report data from UTF-8 to the specified single-byte character set, prior to doing the normal PDF output generation. This SCV allows IAFs own internal built-in production code to be used with UTF-8 in cases where the data is single-byte data. See the UTF-8 Usage topic in the Introduction to this Appendix for more information. GEM_PDF_COMPRESS This SCV enables or disables PDF document compression in situations where IAF creates the PDF file directly itself (rather than via PDFlib). This SCV should be set to a TRUE or FALSE value. The default is TRUE. Unless a DML program itself writes binary data to the document, whenever document compression is disabled IAF produces an entirely non-binary document -- the contents of which can be viewed with a text editor. However, setting this SCV to FALSE is mostly only useful for debugging purposes. Compressed PDF documents can be considerably smaller than the equivalent uncompressed report listing files. GEM_PDF_LIBRARY This SCV can be used to force IAF to always use its own internal PDF production facility or to always use PDFlib. By default IAF will use its own internal PDF production facility if it can and only use PDFlib if it must. The valid values for this SCV are CONDITIONAL, IAF, and PDFLIB. The default is CONDITIONAL. Set this SCV to IAF: to force IAF to use its own internal PDF production facility and to ignore any options (such as owner_password,
IAF PDF Reports and PDF File Production IAF 8.0 DML J-11

PDF Reports and PDF File Production

user_password and permissions) that would otherwise require it to use PDFlib. Note that if a non-core font or non-standard CJK font was specified it will be ignored and Courier will be used instead. Set this SCV to PDFLIB to force IAF to use PDFlib, even if it would not otherwise choose to do so. Set this SCV to CONDITIONAL (or dont set it) to permit IAF to make its own decision. The following SCVs are only applicable when the /PDF qualifier is used with the REPORT form statement to cause a PDF document to be created in lieu of a report listing.

Report Form SCVs

Use the following SCVs during PDF report generation: GEM_REPORT_PDF This SCV enables production of PDF reports by default. When set TRUE, reports are output in PDF format even if they do not explicitly specify a /PDF qualifier. GEM_REPORT_PDF_AUTHOR This SCV sets the default PDF document author if no AUTHOR option is specified. GEM_REPORT_PDF_CELLWIDTH This SCV sets the default PDF cell width if no CELLWIDTH option is specified. GEM_REPORT_PDF_COLOR This SCV sets the default color if no COLOR options are specified. The content is the same as for the COLOR= option of the /PDF qualifier. GEM_REPORT_PDF_CREATOR This SCV sets the default PDF document creator if no CREATOR option is specified.

J-12

IAF PDF Reports and PDF File Production IAF 8.0 DML

PDF Reports and PDF File Production

GEM_REPORT_PDF_ENCODING This SCV sets the default PDF document encoding if no ENCODING option is specified. GEM_REPORT_PDF_FONTNAME This SCV sets the default PDF document font if no FONTNAME option is specified. GEM_REPORT_PDF_FONTSIZE This SCV sets the default PDF document font size if no FONTSIZE option is specified. GEM_REPORT_PDF_KEYWORDS This SCV sets the default PDF document keyword list if no KEYWORDS option is specified. GEM_REPORT_PDF_LANGUAGE This SCV sets the default PDF document language if no LANGUAGE option is specified. GEM_REPORT_PDF_MARGINS This SCV sets the default PDF document margins if no MARGINS option is specified. GEM_REPORT_PDF_MONOSPACE This SCV sets the default monospace value if no MONOSPACE option is specified. GEM_REPORT_PDF_OWNERPASSWORD This SCV sets the default PDF document owner password if no OWNER_PASSWORD option is specified. GEM_REPORT_PDF_PAGESIZE This SCV sets the default PDF document page size if no PAGESIZE option is specified. The content is the same as for the PAGESIZE= option of the /PDF qualifier.

IAF PDF Reports and PDF File Production IAF 8.0 DML

J-13

PDF Reports and PDF File Production

GEM_REPORT_PDF_PAGELAYOUT This SCV sets the default PDF document page layout of no PAGELAYOUT option is specified. GEM_REPORT_PDF_PAGEMODE This SCV sets the default PDF document page display mode if no PAGEMODE option is specified. GEM_REPORT_PDF_PERMISSIONS This SCV sets the default PDF document permissions if no PERMISSIONS option is specified. The content is the same as for the PERMISSIONS= option of the /PDF qualifier. GEM_REPORT_PDF_RENDER This SCV sets the default text rendering if no RENDER option is specified. The content is the same as for the RENDER= option of the / PDF qualifier. GEM_REPORT_PDF_ROTATE This SCV sets the default page rotation if no ROTATE option is specified. The content is the same as for the ROTATE= option of the /PDF qualifier. GEM_REPORT_PDF_USERPASSWORD This SCV sets the default PDF document user password if no USER_PASSWORD option is specified. GEM_REPORT_PDF_VIEWERPREFERRENCES This SCV sets the default PDF document viewer preferences if no VIEWERPREFERENCES option is specified.

J-14

IAF PDF Reports and PDF File Production IAF 8.0 DML

PDF Reports and PDF File Production

Text File SCVs

The following SCVs are identical to the above SCVs, but they are only applicable when the /PDF qualifier is used with the OPEN_TEXT/ CREATE statement to cause a PDF document to be created in lieu of a text file: GEM_TEXT_PDF_AUTHOR GEM_TEXT_PDF_CELLSIZE GEM_TEXT_PDF_COLOR GEM_TEXT_PDF_CREATOR GEM_TEXT_PDF_ENCODING GEM_TEXT_PDF_FONTNAME GEM_TEXT_PDF_FONTSIZE GEM_TEXT_PDF_KEYWORDS GEM_TEXT_PDF_LANGUAGE GEM_TEXT_PDF_MARGINS GEM_TEXT_PDF_MONOSPACE GEM_TEXT_PDF_OWNERPASSWORD GEM_TEXT_PDF_PAGESIZE GEM_TEXT_PDF_PAGELAYOUT GEM_TEXT_PDF_PAGEMODE GEM_TEXT_PDF_PERMISSIONS GEM_TEXT_PDF_RENDER GEM_TEXT_PDF_ROTATE GEM_TEXT_PDF_USERPASSWORD GEM_TEXT_PDF_VIEWERPREFERENCES

IAF PDF Reports and PDF File Production IAF 8.0 DML

J-15

PDF Reports and PDF File Production

PDFlib SCVs
The following SCVs are only applicable when PDFlib is used. However, the GEM_PDF_LIBRARY SCV can be used to force IAF to use PDFlib rather than its own built-in PDF production facilities. GEM_PDFLIB_COMPRESS Sets the PDF document compression level. Please refer to your PDFlib documentation for more information concerning the PDF document compression level setting. GEM_PDFLIB_LIBRARY By default IAF looks for the PDFlib API in the following platform specific locations: 1. On OpenVMS platforms: PDFLIBSHR with a default of file specification of GEM_RUN:.EXE. Thus on this platform the logical PDFLIBSHR can also be defined. 2. On UNIX platforms: $GEM_RUN/libpdf.sl or $GEM_RUN/libpdf.so. 3. On Windows platforms: %GEM_RUN%\pdflib.dll To override the default, set this SCV to the filename of the PDFlib shareable image (OpenVMS), shared library (UNIX) or dynamic link library (Windows). IAF will look for and directly call the function PDF_get_api. All other PDFlib API calls are done indirectly via function pointers returned by the PDF_get_api function. Therefore, in so far as IAF is concerned, this is the only function that needs to be exported. GEM_PDFLIB_LICENSE This SCV can contain your PDFlib license key in an SCV. Note that PDFlib operates in demo mode unless you provide a valid PDFlib license key. Demo mode places large diagonal www.pdflib.com watermarks on each page produced. A non-null value for this SCV forces IAF to use PDFlib rather than its own built-in PDF production facilities.

J-16

IAF PDF Reports and PDF File Production IAF 8.0 DML

PDF Reports and PDF File Production

GEM_PDFLIB_LICENSEFILE This SCV can contain the file specification of a file which contains your PDFlib license key. Note that the GEM_PDFLIB_LICENSE SCV takes precedence. A non-null value for this SCV forces IAF to use PDFlib rather than its own built-in PDF production facilities. GEM_PDFLIB_RESOURCEFILE This SCV sets the file specification of the PDFlib resource file, if any. Please refer to your PDFlib documentation for more information concerning PDFlib resource files and why you might want to use them. GEM_PDFLIB_SEARCHPATH This SCV can be used to manually configure the PDFlib CMap resources if they are not detected automatically by PDFlib at run-time. Set this SCV to the point to the CMap folder, for example on Windows, c:\pdflib\resource\cmap. GEM_PDFLIB_TRACE This SCV enables or disables PDFlib tracing. Please refer to your PDFlib documentation for more information concerning PDFlib tracing. GEM_PDFLIB_TRACEFILE This SCV sets the file specification for the PDFlib trace file. Please refer to your PDFlib documentation for more information concerning PDFlib tracing.

IAF PDF Reports and PDF File Production IAF 8.0 DML

J-17

Appendix K

CPANEL DML Statement

Introduction

Introduction
CPANEL is used to add a task item to the Smart Client Container DMLDesktop TaskPad. When clicked, the task item sends a command to an SCC Application add-in. There are 5 types of tasks that can be added to the TaskPad: tasks that perform a DML command in this add-in tasks that run a facility in this add-in tasks that navigate to a URL in this add-in tasks that run a web application in this add-in tasks that send a command to a different add-in Every CPANEL command must have a /text qualifier and one or more / parameter qualifiers. The /text qualifier specifies the text string that will be displayed in the TaskPad. The /parameter qualifiers are used to specify attributes or properties for the command that is sent to the app add-in. Some attributes apply for all app add-ins and are defined and documented by the Smart Client Container - these are called common attributes below. Some attributes are specific to a particular app add-in and are defined and documented by the app add-in - these are called specific attributes below. The main challenge facing the DML programmer is figuring out what to specify for the / parameter qualifier. The sections that follow show examples of using CPANEL to add the five different types of TaskPad items. Later, examples are shown for replacing and removing TaskPad items.

Example: Perform a DML Command in this Add-in

cpanel /text="TED" & /parameter= (name="application" value="DMLDesktop") & /parameter= (name="TagName" value="GemPerform") & /parameter= (name="dml" value="perform 'GEM_RUN:gem_ted'")

The /parameter qualifier names shown are all required for this type of app add-in command.

K-2

CPANEL DML Statement IAF 8.0 DML

Introduction

/parameter= (name="application" value="DMLDesktop") &

The "application" attribute is common and here specifies that "DMLDesktop" is the name of the app add-in that is the target for this command.
/parameter= (name="TagName" value="GemPerform") &

The "TagName" attribute is specific to the DMLDesktop add-in. GemPerform is one of the allowed values for TagName. This will cause the DMLDesktop add-in to perform some DML.
/parameter= (name="dml" value="perform 'GEM_RUN:gem_ted'")

The "dml" attribute is specific to the DMLDesktop add-in. It is required when the TagName attribute has a value of "GemPerform" and specifies the DML command to be performed.

Example: Run a Facility in this Add-in

cpanel /text="Customer Balances" & /parameter= (name="application" value="DMLDesktop") & /parameter= (name="TagName" value="GemFacility") & /parameter= (name="database" value="FIN") & /parameter= (name="system" value="ACCOUNTS_RECEIVABLE") & /parameter= (name="facility" value="AR_I_003")

This TaskPad item when clicked runs the facility. The /parameter qualifier names shown are all required for this type of app add-in command. Notice that TagName has a different value (GemFacility). With this value for TagName, the add-in specific attributes database, system and facility are all required by the DMLDesktop add-in. To do a drill-in to go to a customer, add a parameter for StartUpParams, to give:
cpanel /text="Customer Balances" & /parameter= (name="application" value="DMLDesktop") & /parameter= (name="TagName" value="GemFacility") & /parameter= (name="database" value="FIN") & /parameter= (name="system" value="ACCOUNTS_RECEIVABLE") & /parameter= (name="facility" value="AR_I_003") &

CPANEL DML Statement IAF 8.0 DML

K-3

Introduction

/parameter= (name="StartUpParams" value="US|A100")

The "StartUpParams" attribute is specific to the DMLDesktop add-in, and is optional for TagName=GemFacility.

Example: Navigate to a URL in this Add-in

cpanel /text="Show Zip" & /parameter= (name="application" value="DMLDesktop") & /parameter= (name="TagName" value="URL") & /parameter= (name="url" value="http://maps.google.com/ maps?q=30328")

The /parameter qualifier names shown are all required for this type of app add-in command. Compare this with the first example and notice the TagName attribute has a different value (URL). Notice also that with Tagname=URL, the add-in specific "url" attribute is required.

Example: Run a Web Application in this Add-in

cpanel /text="Meta Man" & /parameter= (name="application" value="DMLDesktop") & /parameter= (name="TagName" value="WebApplication") & /parameter=(name="url" value="http://host/IAF/IAFWebSite/DDFMain.aspx")

The /parameter qualifier names shown are all required for this type of app add-in command. The TagName attribute has a value of WebApplication for this type of task. With Tagname=URL, the add-in specific "url" attribute is required.

Example: Send a Command to a Different Add-in

cpanel /text="Map" & /parameter= (name="application" value="Web") & /parameter= (name="url" value="http://maps.google.com/ maps?q=30328")

This TaskPad item when clicked sends a command to the Web app add-in to show a Google map.

K-4

CPANEL DML Statement IAF 8.0 DML

Introduction

The /parameter qualifier names shown are all required for this type of app add-in command. The "application" attribute identifies "Web" as the name of the app add-in target for this command. This add-in requires the "url" attribute.

Replacing TaskPad Items

Replace an item in the TaskPad by using a CPANEL command with the / text qualifier specifying the item to be replaced. For example, to change the TaskPad item added in the previous example above, to give a map of Moose Lake MN instead of Atlanta GA, do the following:
cpanel /text="Map" & /parameter= (name="application" value="Web") & /parameter= (name="url" value="http://maps.google.com/ maps?q=55767")

There are two ways to replace a TaskPad item with a new task displaying different text. For example:
cpanel /text="Map 30328" & /parameter= (name="application" value="Web") & /parameter= (name="url" value="http://maps.google.com/ maps?q=30328") cpanel /text="Map 30328" /remove cpanel /text="Map 55767" & /parameter= (name="application" value="Web") & /parameter= (name="url" value="http://maps.google.com/ maps?q=55767")

As an alternative that eliminates the need to remove the first task, use the optional /ID qualifier:
cpanel /id="map" /text="Map 30328" & /parameter= (name="application" value="Web") & /parameter= (name="url" value="http://maps.google.com/ maps?q=30328") cpanel /id="map" /text="Map 55767" & /parameter= (name="application" value="Web") & /parameter= (name="url" value="http://maps.google.com/ maps?q=55767")

CPANEL DML Statement IAF 8.0 DML

K-5

Introduction

Removing TaskPad Items

To remove an item from the TaskPad, use a CPANEL command identifying the task and specifying the /remove qualifier. For example, to remove the CPANEL item added above:
cpanel /text="Map" /remove

The /remove qualifier is useful when you want to immediately remove an item during the execution of a form. It is rarely needed however, as the default behavior is for TaskPad items to be automatically removed when the form that creates them ends. See the next section and the description of the /GLOBAL qualifier.

Automatic Removal of TaskPad Items

TaskPad items created with CPANEL are automatically removed when the form that creates them ends, unless you specify the /GLOBAL qualifier. Example:
form zip_form /row=3 /col=2 /height=22 /width=78 input_block zip /row=3 /col=15 prompt="Zip Code: " /target=#zipcode #url = "http://maps.google.com/maps?q=" & #zipcode cpanel /text="Map" /global & /parameter= (name="application" value="Web") & /parameter= (name="url" value=#url) end_form

The /GLOBAL qualifier causes the "Map" TaskPad item to remain in the TaskPad when the forms ends.

Simplified Syntax for DMLDesktop User

The syntax described above is very flexible and allows any app add-in to be targeted. However, the CPANEL statement has some additional qualifiers that simplify the syntax for use with the DMLDesktop add-in. This will most likely be the favorite add-in for DML programmers. Consider the first example above:
cpanel /text="TED" & /parameter= (name="application" value="DMLDesktop") & /parameter= (name="TagName" value="GemPerform") &

K-6

CPANEL DML Statement IAF 8.0 DML

Introduction

/parameter= (name="dml" value="perform 'GEM_RUN:gem_ted'")

This can be specified as follows:

cpanel /text="TED" & /dml="perform GEM_RUN:gem_ted"

Similarly, for Example 2:

cpanel /text="Customer Balances" & /parameter= (name="application" value="DMLDesktop") & /parameter= (name="TagName" value="GemFacility") & /parameter= (name="database" value="FIN") & /parameter= (name="system" value="ACCOUNTS_RECEIVABLE") & /parameter= (name="facility" value="AR_I_003") & /parameter= (name="StartUpParams" value="US|A100")

This can be specified as follows:

cpanel /text="Customer Balances" & /facility=FIN.ACCOUNTS_RECEIVABLE:AR_I_003 & /drillin="US|A100"

The /facility qualifier implies all the parameters omitted from the original version. Also, when /facility is used, /drillin can optionally be used to drill into a facility. Similarly, for this Example:
cpanel /text="Show Zip" & /parameter= (name="application" value="DMLDesktop") & /parameter= (name="TagName" value="URL") & /parameter= (name="url" value="http://maps.google.com/ maps?q=30328")

Specify it as follows:
cpanel /text="Show Zip" & /url="http://maps.google.com/maps?q=30328"

The /url qualifier implies all the attributes omitted from the original version. Similarly, for this Example:
cpanel /text="Meta Man" & /parameter= (name="application" value="DMLDesktop") &

CPANEL DML Statement IAF 8.0 DML

K-7

Introduction

/parameter= (name="TagName" value="WebApplication") & /parameter=(name="url" value="http://host/IAF/IAFWebSite/DDFMain.aspx")

Specify it as follows:
cpanel /text="Meta Man" & /web_app="http://host/IAF/IAFWebSite/DDFMain.aspx"

The /web_app qualifier implies all the attributes omitted from the original version.

Miscellaneous Usage Notes

CPANEL is for use from DMLDesktop in the Smart Client Container. If used from iBrowser, GTC (Thin Client) or GCWPro it will simply do nothing - it will not generate an error. Thus to write portable DML code, there is no need to test the %THIN_CLIENT_MODE special variable before using CPANEL.

K-8

CPANEL DML Statement IAF 8.0 DML

Examples

Examples
These are examples of CPANEL calls and the associated UIDL messages:

Example 1 - Add Taskpad item to show web page using the WEB add-in
CPANEL /TEXT="Google Maps" & /ADDIN="WEB" & /PARAMETER= (NAME="url", VALUE="http://maps.google.com/ maps?q=30328")

Example 2 - Remove Taskpad item created in Example 1

CPANEL /TEXT="Google Maps" /REMOVE

Example 3 - Drillin
This example shows how to do a drill-in. First the long-hand, formal syntax:
CPANEL /TEXT="Show Orders" & /PARAMETER= (NAME="TagName", "GemFacility") & /PARAMETER= (NAME="DATABASE", VALUE="FIN") & /PARAMETER= (NAME="SYSTEM", VALUE="SALES_ORDER_PROCESSING") & /PARAMETER= (NAME="FACILITY", VALUE="SOP_I_002") & /PARAMETER= (NAME="StartUpParams", VALUE="01|1|10|0")

Now, the equivalent DML-flavor, friendly shorthand syntax:

CPANEL /TEXT="Show Orders" & /FACILITY=FIN.SALES_ORDER_PROCESSING:SOP_I_002 & /DRILLIN="01|1|10|0"

CPANEL DML Statement IAF 8.0 DML

K-9

Non-Smart Client DMLDesktop Environments

Non-Smart Client DMLDesktop Environments

The CPANEL feature is for Smart Client DMLDesktop users only, currently the only client with a Taskpad. For other clients, such as in iBrowser or Mobile UI Server applications, and also in non UI Server environments, such as Thin Client and GCWPro, it will act as a no-op; it will not generate an error.

K-10

CPANEL DML Statement IAF 8.0 DML

Appendix L DML Unit Testing

Introduction

Introduction
Unit testing tests small elements of software to make sure they perform as they should. These are often single functions, commands, procedures or methods. Unit tests are a collection of automated tests that are run continuously during development to identify when changes or new development has introduced bugs. Several programming environments include testing frameworks to simplify unit testing. Examples are jUnit for Java and NUnit for C#. In the DML world, we have DML features described in this appendix, such as RUN_TESTS and ASSERT.

DML Language Features for Unit Testing

The following features are included in the DML language to assist with unit testing. These are documented in the IAF DML Language Manual: RUN_TESTS ASSERT, ASSERT_FAIL, ASSERT_EQUAL %ASSERT_FAILURE The use of these language features is described in the sections that follow.

L-2

DML Unit Testing IAF 8.0 DML

Introduction

Unit Tests without RUN_TESTS and ASSERT

Before looking at samples using RUN_TESTS and ASSERT, consider how tests might have been written previously. (These examples are taken from actual tests).

Example 1
!A00040.DML !Mask a NULL string, uses the same length as mask. procedure_form A00040 #A = (MASK('!@@@@@@@@@@',"")) if (#A = " ") "a00040.result" AS A00040

OPEN_TEXT/CREATE

WRITE_LINE A00040 "========== A00040 PASSED ==========" CLOSE_TEXT A00040 else OPEN_TEXT/CREATE "a00040.result" AS A00040

WRITE_LINE A00040 "********** A00040 FAILED **********" CLOSE_TEXT A00040 end_if end_form

This first example writes "PASSED" or "FAILED" to a result file. Running a test suite consisting of hundreds of such tests involves a postprocessing script to analyze all the results and produce a report. Such a script is needed for all the IAF platforms (Windows, UNIX and VMS). Note also that when running, the test does not actually fail; it always returns %SUCCESS.

Example 2
procedure_form main perform test_len perform test_concat end_form procedure_form test_len #len = len("hello") if (#len <> 5) print "LEN failed"

DML Unit Testing IAF 8.0 DML

L-3

Introduction

exit(%failure) end_if print "LEN passed" end_form procedure_form test_concat #A = "Hello" #B = "World" #C = #A & #B if (#C <> "HelloWorld") print "concatenation failed" exit(%failure) end_if print "concatenation passed" end_form

The procedure_form main is used as there is no easy way to perform all the forms in a file, and the verification logic is quite verbose.

Using RUN_TESTS and ASSERT

Rewriting the tests above to use one of the ASSERT statements and RUN_TESTS:
procedure_form TEST_A00040 #A = (MASK('!@@@@@@@@@@',"")) assert (#A = " end_form procedure_form test_len #len = len("hello") assert_equal (5) (#len) /msg="LEN failed" end_form procedure_form test_concat #A = "Hello" #B = "World" #C = #A & #B assert_equal ("HelloWorld") (#C) /msg="concatenation failed" end_form ")

L-4

DML Unit Testing IAF 8.0 DML

Introduction

The tests are simplified using ASSERT_EQUAL, and the procedure form main is no longer needed. RUN_TESTS automatically runs all forms named TEST_*. ASSERT and RUN_TESTS simplify the creation and running of test suites consisting of hundreds of tests.

Designing and Developing Unit Tests

These are the steps to follow when writing tests:
1. 2. 3. 4. Identify a small piece of functionality to be tested. Setup the preconditions for the test. Write a test to test the functionality. Within the test, specify one or more assertions to verify that the code works correctly by comparing actual results against expected results. Clean up after the test. Repeat steps 1 thru 5 for other pieces of functionality.

5. 6.

Best Practices
Keep these items in mind when working with DML unit tests: If the code being tested does not work as expected the test should fail and fail loudly. The easiest way to make the test fail is to use one of the ASSERT statements (ASSERT, ASSERT_FAIL, ASSERT_EQUAL).

Console Testing
Testing using gem_console from a bat file allows the tests to be run automatically, such as after a nightly build. The following is a sample bat file.
@echo off

DML Unit Testing IAF 8.0 DML

L-5

Introduction

REM GEM_RUN_TESTS.BAT REM REM EXITS with: REM ERRORLEVEL = 0 if tests PASS REM ERRORLEVEL = 1 if tests FAIL

REM Setup Environment set GEM_EXIT_WITH_STATUS=TRUE

echo print %%version > temp.tmp echo invoke "sa\gembase\inv73_demo" as inv /e=mssql>> temp.tmp echo run_tests >> temp.tmp

REM Run GEMBASE, and check GEMBASE exit status. gem_console < temp.tmp

IF %ERRORLEVEL% == 1 GOTO PASSED ECHO FINAL STATUS IS FAILED del temp.tmp REM Exit bat script with non-zero errorcode. EXIT /B 1

:PASSED ECHO FINAL STATUS IS PASSED del temp.tmp REM Exit bat script with zero errorcode. EXIT /B 0

L-6

DML Unit Testing IAF 8.0 DML