OS/2 Shareware BBS: Product/Product.zip/visdevin.zip/FTD1OAD2.INF

OS/2 Help File | 1994-07-12 | 862KB | 35,226 lines

ΓòÉΓòÉΓòÉ 1. Notices ΓòÉΓòÉΓòÉ

Note!
Before using this information and the product it supports, please read the
general information under Notices .

First Edition (July 1994)

This edition applies to Release 1 Modification Level 0 of IBM Visualizer
Development for OS/2 (Program Number 5622-421), and to all subsequent versions,
releases, and modifications until otherwise indicated in new editions. Consult
the latest edition of the applicable IBM system bibliography for current
information on this product.

Order publications through your IBM representative or the IBM branch office
serving your locality. Publications are not stocked at the address given below.

A form for readers' comments appears at the back of this publication. If the
form has been removed, address your comments to:

IBM United Kingdom Limited
Warwick Software Development Laboratory
PO Box 31, Birmingham Road
WARWICK
United Kingdom  CV34 5JL

When you send information to IBM, you grant to IBM a non-exclusive right to use
or distribute the information in any way it believes appropriate without
incurring any obligation to you.

(C) Copyright International Business Machines Corporation 1993,1994. All rights
reserved.
Note to U.S. Government users--Documentation related to restriced rights--Use,
duplication or disclosure is subject to restrictions set forth in GSA ADP
Schedule Contract with IBM Corp.


ΓòÉΓòÉΓòÉ 2. Notices ΓòÉΓòÉΓòÉ

References in this publication to IBM products, programs, or services do not
imply that IBM intends to make these available in all countries in which IBM
operates. Any reference to an IBM product, program, or service is not intended
to state or imply that only IBM's product, program, or service may be used. Any
functionally equivalent product, program, or service that does not infringe any
of IBM's intellectual property rights may be used instead of the IBM product,
program, or service. Evaluation and verification of operation in conjunction
with other products, except those expressly designated by IBM, is the user's
responsibility.

IBM may have patents or pending patent applications covering subject matter in
this document. The furnishing of this document does not give you any license to
these patents. You can send license inquiries, in writing, to:

IBM Corporation
IBM Director of Licensing
208 Harbor Drive
Stamford, Connecticut 06904-2501
U.S.A.

This publication contains examples of data and screens used in daily business
operations.  They are intended only to be illustrative of the types of
functions available in Visualizer Development for OS/2 Version 1 and may
contain the names of individuals, companies, brands, and products.  All of
these names are fictitious, and any similarity to the names and addresses used
by an actual business enterprise is entirely coincidental.  Screens shown in
this publication are intended to be examples and may not be exact
representations of actual screens.

This publication contains sample programs.  Permission is hereby granted to
copy and store the sample programs into a data processing machine and to use
the stored copies for internal study and instruction only.  No permission is
granted to use the sample programs for any other purpose.

Trademarks

Who should read this book

How this book is organized


ΓòÉΓòÉΓòÉ 2.1. Trademarks ΓòÉΓòÉΓòÉ

The following terms, denoted by an asterisk (*), used in this publication, are
trademarks or service marks of IBM Corporation in the United States of America
or other countries:

AS/400                                  Common User Access
CUA                                     DB2
DB2/2                                   DB2/6000
DRDA                                    Extended Services
IBM                                     Multimedia Presentation Manager/2
OS/2                                    OS/400
Presentation Manager                    SAA
SQL/DS                                  SQL/400
System/370                              Systems Application Architecture
Workplace Shell

The following terms, denoted by a double asterisk (**), used in this
publication, are trademarks of other companies, as follows:

Aldus                                   Aldus Corporation
cc:Mail                                 cc:Mail, Inc., a wholly owned
                                        subsidiary of Lotus Development
                                        Corporation
Compuserve                              Compuserve, Inc.
dBASE III                               Borland International, Inc.
Microsoft                               Microsoft Corporation
PC Paintbrush                           ZSoft Corporation
Q+E                                     Q+E Software, Inc.
ZSoft                                   ZSoft Corporation


ΓòÉΓòÉΓòÉ 2.2. Who should read this book ΓòÉΓòÉΓòÉ

This book is for professional application developers who want to use Visualizer
Development for OS/2. It contains a detailed description of Application System
Language (ASL), but is not intended to be a tutorial for nonprogrammers.

Before using this book, you need to be familiar with the information in the
following publications:

o IBM Visualizer Development for OS/2: Introducing, which contains a
  step-by-step guide to developing an application.

o IBM Visualizer Development for OS/2: Using, which introduces Visualizer
  Development and ASL. It explains how to use the Menu editor, the Window
  editor, the Program editor, and the Make facility. It also provides exercises
  for practice.

(You can find these books online in the Development Manuals folder.)


ΓòÉΓòÉΓòÉ 2.3. How this book is organized ΓòÉΓòÉΓòÉ

In this book, Visualizer Development for OS/2 is referred to as Visualizer
Development.

This book documents Visualizer Development and covers the application
development environment and Application System Language that form the
application development component of Visualizer.

The manual is organized as follows:

o Part 1 (Language Summary) provides a quick overview of the language
  statements and objects grouped by function.

o Part 2 (Language Reference) is an alphabetical list of all statements,
  functions, and objects with a description of their parameters, attributes,
  actions, and events.

o Part 3 (Appendixes) contains further reference information.

Advanced programmers can also benefit from the sample programs supplied with
the product in the Development Samples folder.


ΓòÉΓòÉΓòÉ 3. Application System Language summary ΓòÉΓòÉΓòÉ

This chapter summarizes the statements and functions of Application System
Language (ASL) that you can use when you create applications. Built-in objects
and statements for manipulating objects are covered in Objects and attributes .

In this chapter, the language elements are grouped as follows:

o Structuring programs
o Controlling programs
o Debugging programs
o Variables, arrays, and tables
o String and mathematical functions
o Operators
o Format values
o Format symbols
o Communicating with end users

Structuring programs

Controlling programs

Communicating with end users

File name and location

Debugging programs

Variables, arrays, and tables

String functions

Mathematical functions

Operators

Format values

Formatting data


ΓòÉΓòÉΓòÉ 3.1. Structuring programs ΓòÉΓòÉΓòÉ

There are statements that specify event blocks and procedures, and statements
that specify the flow of control in these blocks.

Specifying blocks

Flow of control


ΓòÉΓòÉΓòÉ 3.1.1. Specifying blocks ΓòÉΓòÉΓòÉ

These are the statements that specify procedures and event blocks:

ON                      Identifies the statements to be executed when an event
                        occurs

PROCEDURE               Identifies statements to be executed as a procedure or
                        function

RETURN                  Ends a PROCEDURE or event block


ΓòÉΓòÉΓòÉ 3.1.2. Flow of control ΓòÉΓòÉΓòÉ

These are the statements that specify the flow of control in event blocks and
procedures:

CALL                    Invokes a procedure or object action

CASE ... WHEN ... OTHERWISE ... END Processes one of several sections of code,
                        depending on the value of an expression

                        WHEN identifies a value of a CASE expression

                        TRUE identifies a statement to be executed if the
                        expression is true

                        FALSE identifies a statement to be executed if the
                        expression is false

                        NULL identifies a statement to be executed if the
                        expression has a NULL value

                        OTHERWISE identifies a statement to be executed if no
                        WHEN condition is true

DO...END                Enclose statements that are to be processed together.
                        The DO...END structure can be used anywhere that a
                        single statement can.

                        LEAVE terminates a DO...END block

                        TERMINATE ends a repeating block

                        ITERATE starts a new iteration of a repeating block

                        UNTIL repeats a statement until a condition is true,
                        testing the condition after executing the statement

                        WHILE repeats a statement while a condition is true,
                        testing the condition before executing the statement

FORGIVE                 Prevents an error in a statement from invoking the ON
                        ERROR block

IF ... THEN ... ELSE    Tests a condition

                        THEN identifies a statement to be executed when an IF
                        condition is true. THEN is optional

                        ELSE identifies a statement to be executed when an IF
                        condition is false

NOTHING                 Does nothing, useful as a place holder


ΓòÉΓòÉΓòÉ 3.2. Controlling programs ΓòÉΓòÉΓòÉ

There are statements that you can use to control when programs start and stop.

Signalling programs

Synchronizing programs

Ctrl Break

Events


ΓòÉΓòÉΓòÉ 3.2.1. Signalling programs ΓòÉΓòÉΓòÉ

The statements that signal programs are as follows:

QUEUE PROGRAM           Signals an event to an active program. The event is
                        queued for execution until the initiating program has
                        finished and there is a wait state.

RUN PROGRAM             Signals an event to the requested program immediately.
                        After the program has been executed, the initiating
                        program continues.

START                   Causes another program to be loaded, and its ON START
                        block to be executed immediately.

STOP                    Stops execution of the current program and makes it
                        inactive.


ΓòÉΓòÉΓòÉ 3.2.2. Synchronizing programs ΓòÉΓòÉΓòÉ

The following statements can be used to synchronize programs:

WAIT PROGRAM            Suspends a program until another program ends (or
                        cancels the suspended state with SIGNAL PROGRAM).

SIGNAL PROGRAM          Cancels the suspension of a calling program caused by a
                        WAIT statement.


ΓòÉΓòÉΓòÉ 3.2.3. Ctrl Break ΓòÉΓòÉΓòÉ

A statement and a function control the handling of Ctrl Break entered by the
user:

BREAK                   Controls handling of a control break entered by the
                        user.

BREAK()                 True if at least one control break is outstanding.


ΓòÉΓòÉΓòÉ 3.2.4. Events ΓòÉΓòÉΓòÉ

These are the events that you can use in your application:

AB                      Selecting an item from a menu bar

ADVISE                  Issuing an ADVISE from DDECLIENT

BREAK                   The control break key (Ctrl+Break)

CONTRACT                The contract (-) symbol on a folder is selected

DATA                    Data entry in a control object, or a DDE ADVISE occurs

DATASELECT              Selecting a row in a table editor

DESKTOP                 A request to resize a window

DISCARD                 An object is moved, or dropped on the shredder

DRAG                    A graphics object has been dragged on a window

ENTER                   The ENTER key

ERROR                   A run-time processing error

ESCAPE                  The ESCAPE key

EXPAND                  The expand (+) symbol on a folder is selected

HELP                    Selecting help

INFORM                  Selecting a hypertext INFORM field (from HELP)

INITIATE                A DDE conversation is initiated

LISTDATA                Inserting or deleting a line in a list control

LISTSCROLL              Scrolling a list control

OPEN                    When double-clicking in a list control

ORDER                   When order is selected in VIEWORDER

PRINT                   An object is dropped on a printer

PROPERTIES              Changing the desktop

QUEUE                   A QUEUE PROGRAM statement

QUIT                    A request to close a window or server

SCROLL                  Moving a scroll bar on a window

SCHEME                  Dropping a font on a window

SELECT                  Selecting an object in a window opened by the task

SIGNAL                  A signal from a Presentation Manager control

SOURCE                  A DDECLIENT requesting data

START                   A program being started as a task

STOP                    A STOP statement

TARGET                  A DDECLIENT delivering data

TIMER                   A timer reaching one of its preset alarm times, or a
                        multimedia object passing a cue point.

For a list of events and the objects that can signal them, see Events .


ΓòÉΓòÉΓòÉ 3.3. Communicating with end users ΓòÉΓòÉΓòÉ

The statements or functions, other than windows and controls, that you can use
to communicate with users are as follows:

DIALOG()                Displays a message and returns a code representing the
                        push button on the message window that the user presses

MESSAGE                 Displays a message

ERROR                   Displays an error message

SOUND                   Produces a sound of a specified frequency and duration


ΓòÉΓòÉΓòÉ 3.4. File name and location ΓòÉΓòÉΓòÉ

These functions act on file names.

FULLPATH()              Returns the fully qualified name from a location name
                        and a file name

LOCATION()              Returns the location from a fully qualified name

NAME()                  Returns the file name from a fully qualified name


ΓòÉΓòÉΓòÉ 3.5. Debugging programs ΓòÉΓòÉΓòÉ

This statement is designed to help you debug programs:

TRACE                   Produces a trace of statements executed in your program

Use the user library function TRACE() for access to the trace log.


ΓòÉΓòÉΓòÉ 3.6. Variables, arrays, and tables ΓòÉΓòÉΓòÉ

The statements and functions that act on variables, arrays and tables are as
follows:

ANALYZE                 Scans one or two columns in a table to analyze the data

CLEAR                   Clears a variable, array element, or table row

COPY                    Copies a variable, array element, or table row

COPY                    Copies a variable, array element, or table row

COUNT()                 Counts the occurrences of the first non-NULL data type
                        found in an array

DATE()                  Converts a string or a number into a date.

DECLARE                 Declares the existence of objects and variables

DEFINE statement        Allocates an array, or specifies the number of items in
                        an array, or resizes an array

DEFINED()               Tests whether the value of an expression is non-NULL

DELETE                  Deletes a variable, array element, or table row

ENTRIES()               Returns the number of entries in an array or table

FIND()                  Returns the position of a specified value in an array
                        or table

GATHER                  Finds the unique values in an array

IF()                    Tests a condition and returns an expression as a result

INDEX                   Indexes a table

INSERT                  Inserts an element into an array, or a row into a table

INSERT()                Inserts values into an array or table and returns the
                        index number of the inserted element or row

LET                     Assigns a value to a variable

MAX()                   Returns the maximum of a set of values

MIN()                   Returns the minimum of a set of values

NOVALUE()               Returns 1 if a variable is of datatype NULL

NULL()                  Tests whether a single value is of data type NULL

POINTER()               Returns a pointer that identifies a specified variable

RENAME                  Renames a variable, array element, or table row

RETYPE()                Evaluates an expression, giving it the data type of a
                        named variable

ROW()                   Returns the relative position of a row in a table

TIME()                  Converts a string or a number into a time.

TOTAL()                 The sum of a series

UNIQUE()                Returns a unique string

VALUE()                 Returns the first of its arguments that is not NULL

VERIFY()                Checks whether array elements are convertible


ΓòÉΓòÉΓòÉ 3.7. String functions ΓòÉΓòÉΓòÉ

The functions that act on strings are as follows. Those functions whose names
start with an extra C are for use with double byte character sets (DBCS)
instead of single byte character sets (SBCS) such as ASCII.

Adding, deleting, overlaying and extending strings

Characters and words in strings

Conversions on strings


ΓòÉΓòÉΓòÉ 3.7.1. Adding, deleting, overlaying and extending strings ΓòÉΓòÉΓòÉ

ADDWORD()               Inserts a substring into a string

DELWORD()               Deletes a substring from a string

OVERLAY() COVERLAY()    Replace part of a string with another string

FULLPATH()              Returns the fully qualified name from a location name
                        and a file name

LOCATION()              Returns the location from a fully qualified name

NAME()                  Returns the file name from a fully qualified name

PAD() CPAD()            Extends a string

STRING()                Builds a string from component parts

TRIM()                  Removes blanks from the beginning or end of a string


ΓòÉΓòÉΓòÉ 3.7.2. Characters and words in strings ΓòÉΓòÉΓòÉ

CHARPOS() CCHARPOS()    The position of the first character of a word

LENGTH() CLENGTH()      The string length in characters

NOVALUE()               Returns 1 if a string is empty or contains only blanks

PLENGTH()               The string length in dialog box units

SCAN() CSCAN()          The position of a substring

WORDPOS() CWORDPOS()    The position of word

WORDS()                 The number of words


ΓòÉΓòÉΓòÉ 3.7.3. Conversions on strings ΓòÉΓòÉΓòÉ

EVALUATE()              A variable that can be evaluated by the ? operator,
                        obtained by compiling the string

SPLIT() CSPLIT()        Part of the string

UPPER()                 The string converted to uppercase

CHAR()                  The numeric parameters are converted to a character
                        string.


ΓòÉΓòÉΓòÉ 3.8. Mathematical functions ΓòÉΓòÉΓòÉ

The mathematical functions provide for arithmetic, trigonometry, and statistics
in calculations.

Arithmetic functions

Statistical functions

Trigonometric functions

Precision


ΓòÉΓòÉΓòÉ 3.8.1. Arithmetic functions ΓòÉΓòÉΓòÉ

The following functions provide arithmetic calculations:

ABS()                   An absolute value

COMPARE()               Comparison of two values (handling NULLs)

DIVIDE()                A quotient (result of a division)

DURATION()              Arithmetic on dates and times

EXP()                   An exponential

FACTORIAL()             A factorial

LOG()                   A logarithm to any base

SQRT()                  A square root

RANDOM()                A pseudo-random positive number


ΓòÉΓòÉΓòÉ 3.8.2. Statistical functions ΓòÉΓòÉΓòÉ

The following functions provide statistical calculations:

STDEV(), STDSAMP()      Standard deviation for a population

STDEV(), STDSAMP()      Standard deviation for a sample

VARIANCE()              Variance for a population


ΓòÉΓòÉΓòÉ 3.8.3. Trigonometric functions ΓòÉΓòÉΓòÉ

The following functions provide trigonometric calculations:

ASIN()                  An arcsine (returns radians)

ASIND()                 An arcsine (returns degrees)

ACOS()                  An arccosine (returns radians)

ACOSD()                 An arccosine (returns degrees)

ATAN()                  An arctangent  (returns radians)

ATAND()                 An arctangent  (returns degrees)

COS()                   Cosine of an angle in radians

COSD()                  Cosine of an angle in degrees

DEGREES()               Degrees, converted from radians

RADIANS()               Radians, converted from degrees

SIN()                   Sine of an angle in radians

SIND()                  Sine of an angle in degrees

TAN()                   Tangent of an angle in radians

TAND()                  Tangent of an angle in degrees


ΓòÉΓòÉΓòÉ 3.8.4. Precision ΓòÉΓòÉΓòÉ

The following functions control precision:

ADJUST()                Adjusts, rounds, or truncates numeric values

PRECISION               Specifies the number of decimal places to which
                        calculations are carried out


ΓòÉΓòÉΓòÉ 3.9. Operators ΓòÉΓòÉΓòÉ

The following operators are available:

Monadic operators

Arithmetic operators

Comparisons

Logical operators

String concatenation

Assignments

Order of operations


ΓòÉΓòÉΓòÉ 3.9.1. Monadic operators ΓòÉΓòÉΓòÉ

These are operators that act on the value immediately following them. They all
operate on numbers:

 -                      Negative

 \+                     Increment by 1

 \-                     Decrement by 1

 \*                     Double

 \/                     Halve

 \^  or \**             Square

 \                      Logical NOT (return 0 if the operand is nonzero,
                        otherwise 1)

 ?                      Indirect reference

The  ?  operator uses the value following it to refer indirectly to another
data item. The operand can be a pointer value created by the POINTER() function
or the PROCEDURE() function, a character string naming the data item, or an
expression created by the EVALUATE() function.


ΓòÉΓòÉΓòÉ 3.9.2. Arithmetic operators ΓòÉΓòÉΓòÉ

These operators combine the value before the operator with the value after it.
They all act on numbers:

 +                      Add

 -                      Subtract

 *                      Multiply

 /                      Divide

 %                      Percentage

 **  or ^               Raise to a power

 //                     Remainder after division

                        The sign of the remainder is taken from the sign of the
                        quotient.


ΓòÉΓòÉΓòÉ 3.9.3. Comparisons ΓòÉΓòÉΓòÉ

These compare the value before the operator with the value after it. They
return a numeric result of 1 (true), or 0 (false). If either of the values is
NULL, they return NULL. They act on any data values.

For comparisons that allow NULL values, and for three-way or four-way
comparisons, see the function COMPARE() .

 <                      Less than

 \<                     Not less than

 <=                     Less than or equal to

 =                      Equal to

 \=                     Not equal to

 >=                     Greater than or equal to

 >                      Greater than

 \>                     Not greater than

 <>                     Not equal to

 ==                     Equal to, and identical in case

 \==                    Not equal to, or not identical in case

The  =  operator is not case sensitive when used with SBCS strings, but is case
sensitive when used with DBCS strings. SBCS and DBCS representations of the
same character are considered different.

Comparison operators do not treat trailing SBCS spaces as part of a string, but
they do treat trailing DBCS spaces as part of a string.


ΓòÉΓòÉΓòÉ 3.9.4. Logical operators ΓòÉΓòÉΓòÉ

These operators act on logical values, 1 (true) or 0 (false), and return a
result of 1 (true) or 0 (false). Any nonzero operand is treated as 1 (true).

 &                      AND

 |                      OR

 \                      NOT


ΓòÉΓòÉΓòÉ 3.9.5. String concatenation ΓòÉΓòÉΓòÉ

This operator joins two strings, making a single string. It has two alternative
symbols:

 ||  or ~               Concatenate strings


ΓòÉΓòÉΓòÉ 3.9.6. Assignments ΓòÉΓòÉΓòÉ

Assignment operators assign a value. Most also perform an operation. For
example:


LET x += 6

has the same effect as:


LET x = x+6

 =                      Assign

 +=                     Add to

 -=                     Subtract from

 *=                     Multiply by

 /=                     Divide by

 //=                    Remainder on dividing by

 %=                     Percentage

 &=                     Logical AND with

 |=                     Logical OR with

 ||=  or ~=             Concatenate with


ΓòÉΓòÉΓòÉ 3.9.7. Order of operations ΓòÉΓòÉΓòÉ

Operators in an expression are evaluated in the following order of precedence:

 **                     Power

*, /, %, //             Multiply, Divide, Percentage, Remainder

 +, -                   Add, Subtract

 ||, ~                  Concatenate

 <, <=, =, ==, >=, >, <>, \=, \==, \<, \>  Compare

 |, &                   Logically combine

Monadic operators are evaluated before any of these. Parentheses can be used to
override the normal order.


ΓòÉΓòÉΓòÉ 3.10. Format values ΓòÉΓòÉΓòÉ

These functions return format values that you can use for formatting output to
files:

SPACE()                 Spaces required

LINE()                  New lines required

PAGE()                  New pages required

POSITION()              Position

TAB()                   Tabs required


ΓòÉΓòÉΓòÉ 3.11. Formatting data ΓòÉΓòÉΓòÉ

This section lists the formatting symbols that you can use to specify how items
of data are displayed. There are different sets of formatting symbols for each
of the data types NUMERIC, DATE, and TIME.

To specify how a variable is displayed, set the value of its FORMAT attribute
to a string containing the appropriate formatting symbols. The following
statement, for example, sets the FORMAT attribute of the variable salary  to
provide a currency sign, a left-justified number that uses a thousands
separator, and two decimal places:


LET salary[0]'FORMAT = "Ы,<2"
! salary is displayed as Ы22,400.00 or DM22.400,00

In formatting strings, uppercase and lowercase letters have the same effect.
This section shows letters that represent elements of the data (hours, for
example) in lowercase, and it shows letters that provide other features in
uppercase. The tables in this section represent a space character by using the
symbol for a blank:  .

Formatting NUMERIC data

Formatting dates

Formatting times


ΓòÉΓòÉΓòÉ 3.11.1. Formatting NUMERIC data ΓòÉΓòÉΓòÉ

This section lists the symbols that you can use to specify how NUMERIC data is
displayed.

A formatting string for NUMERIC data must contain a justification symbol such
as  <  to represent a left-justified number or a  >  to represent a
right-justified number. You can include other symbols from the following
tables. Use them in the order that they are given in the tables.

There are four ways to indicate the sign of a number: leading  +  and -  signs,
trailing  +  and -  signs, parentheses for negatives, or  CR and DB. You can
include symbols to indicate the sign of a number in only one of these four
ways. So, for example, you can use CR  on its own or together with DB, but you
cannot use DB  to indicate positives together with parentheses to indicate
negatives.

There are three special ways to represent the number zero: as a space, as a 0,
or as a dash. You can include symbols to represent zero in only one of these
ways.

The default format provides a leading minus sign to indicate a negative number,
and a number of decimal places that is defined by the PLACES attribute of the
PROFILE object. If the number of decimal places is 2, for example, the default
format corresponds to the formatting string  -<2.

These are the symbols that you can use in formatting strings for numbers:
frame=rules rules=none expand.

 +                      A leading plus sign for positive numbers. This
                        suppresses the default minus sign for negative numbers.

 -                      A leading minus sign for negative numbers. This is the
                        default. When used with  +, it restores the minus sign
                        for negative numbers.

 Ы                      A leading currency sign. This is specified by Ы, but
                        displayed as the symbol contained in the CURRENCY
                        attribute of the PROFILE object.

 ,                      Thousand separators. This is specified by the comma
                        symbol, but displayed as the symbol contained in the
                        THOUSEPAR attribute of the PROFILE object.

 ( )                    Parentheses around negative numbers.

 <                      The number, left justified. This symbol, or another
                        justification symbol such as  >, must be present.

0 - 9                   Zero through nine decimal places. The decimal point is
                        displayed as the symbol contained in the DECSEPAR
                        attribute of the PROFILE object.

                       Spaces in place of the decimal point and all the
                        figures after it.

 +                      A trailing plus sign for positive numbers.

 -                      A trailing minus sign for negative numbers.

DB                      A trailing debit sign DB  for positive numbers.

CR                      A trailing credit sign CR  for negative numbers.

 )                      Parentheses around negative numbers.

 /                      A space to represent the number zero.

 /0                     A zero (with no decimal point or decimal places) to
                        represent the number zero.

 /-                     A dash to represent the number zero.

Here are some more examples of numeric formats:

This format             Provides numbers like this:
 <3                     -1.262  0.000  3.434
 +-<1                   -1┬╖3   0┬╖0   +3┬╖4
 (Ы<)                   (Ы1.26) Ы0·00  Ы3·43
 <0cr/-                 1CR   -    3


ΓòÉΓòÉΓòÉ 3.11.2. Formatting dates ΓòÉΓòÉΓòÉ

This section lists the symbols that you can use to specify how DATE data is
displayed.

Dates can contain any of these four elements: period in the day (0-47), day,
month, year. These are indicated in the formatting string by the letters  p
for period, d  for day,  m  for month, and y  for year.

A date format must include the month, except for these two special formats:

d y       The day number (0-366) in the year, together with the year
y         The year alone.

The elements of a date format must be in the order period, day, month, year,
except for these three special formats:

y m d     For year, month, day
m d       For month, day
m d y     For month, day, year.

The default format is defined by the DATEFORMAT attribute of the PROFILE
object. It might, for example, correspond to the formatting string  C d-m-yy,
to provide dates that look like:  31-1-91.

You can include the following characters in the formatting string for a date,
in order to modify the format provided:     frame=rules rules=none expand.

  . / -                A separator character between the elements. If none of
                        these symbols is present, then the elements of the date
                        are not separated, and have leading zeros when less
                        than 10.

C                       Two digits for period, day, and month elements, with a
                        leading space when an element is less than 10. If the
                        symbol C  is not present then leading spaces are
                        suppressed from period, day, and month elements that
                        are less than 10.

yy                      Two digits for the year element, with a leading zero if
                        necessary (2006, for example, is shown as 06 ). If the
                        year element is specified as y, or as yyyy, then the
                        year is shown as four digits.

0                       Leading zeros for elements that are less than 10.

N                       The name of the day or month.

                         Nd  provides the name of the day together with the day
                        number.  Nm  provides the name of the month without the
                        month number.

                        The symbol N  can only appear in these positions
                        (immediately before d  or m ). It can appear in both
                        positions to provide the name of the day, the day
                        number, and the name of the month.

                        When N  appears, then the date separator character is
                        suppressed. Numeric elements are then separated by
                        spaces.

                        The default day and month names are three-letter
                        abbreviations.

r                       Roman numerals for the month

mm                      Full day and month names.

                        If N  is not used in the formatting string, then  mm
                        has the same effect as C.

th                      An ordinal day number ( 31st, for example).

S                       DBCS characters for days, day names, months, and years.

ee                      DBCS short era name and year ( Hei 2, for example).

eeee                    DBCS full era name and year ( Heisei 2, for example).

Here are some more examples of date formats:

This format             Provides dates like this:
d y                     031-1991
 d-m-y                  31-1-1991
dmyy                    310191
mmNdy                   Thursday 1 31 1991

The example below shows how to change date formats


! salarydate has a data type of DATE and its date format
! is "YYYY-0M-0D". The current value is the date 1993-04-28.
! Use DATEFORMAT to change the format
LET salarydate[0]'DATEFORMAT="d-m-y"
! salarydate will now be displayed as  28-4-1993


LET salarydate[0]'DATEFORMAT="NdNmy"
! salarydate will now be displayed as  Wed 28 Apr 1993


ΓòÉΓòÉΓòÉ 3.11.3. Formatting times ΓòÉΓòÉΓòÉ

This section lists the symbols that you can use to specify how TIME data is
displayed.

Times can contain any of these four elements: hours, minutes, seconds,
centiseconds. These are indicated in the formatting string by the letters  h
for hours, m  for minutes,  s  for seconds, and c  for centiseconds.

A time format must include at least two elements, and one of its elements must
be minutes.

The elements of a time format must be in the order hours, minutes, seconds,
centiseconds.

The default format is defined by the TIMEFORMAT attribute of the PROFILE
object. It might, for example, correspond to the formatting string  hh:mm A, to
provide times that look like:


08:56 P.M.

You can include the following characters in the formatting string for a time,
in order to modify the format provided:     frame=rules rules=none expand.

  , . :                Separators between the elements. The separator between
                        hours, minutes, and seconds is defined by the TIMESEPAR
                        attribute of the PROFILE object. The separator between
                        seconds and centiseconds is a decimal point (defined by
                        the DECSEPAR attribute of the PROFILE object). (The 
                        symbol indicates a blank space.)

                        When there are separators between the elements, then
                        the first element has a leading space if is less than
                        10.

mm                      A leading zero for the minutes element if it is less
                        than 10. (This is the default unless minutes is the
                        first element and a separator is in use.)

hh mm                   A leading zero for the hours element if it is less than
                        10. (This is the default unless hours is the first
                        element and a separator is in use.)  hh must be used
                        together with mm.

Here are some more examples of time formats:

This format             Provides times like this:
 h m s                  20:56:30
hma                     0856 P┬╖M┬╖
 h m a                   8:56 P┬╖M┬╖
 hh mm a                08:56 P┬╖M┬╖

The example below shows how to change time formats for displaying data.


! starttime has a data type of TIME and its timeformat
! is "HH:MM:SS". The current value is the time 08:30:25
! Use TIMEFORMAT to change the format
LET starttime[0]'TIMEFORMAT="h m a"
! starttime will now be displayed as  8:30 A.M.


ΓòÉΓòÉΓòÉ 4. Objects and attributes ΓòÉΓòÉΓòÉ

This chapter contains a summary of the built-in objects which you can use for
displaying information. For a table of the attributes of objects and data that
can be modified by ASL, see . (Attributes that are set on OPEN then read-only
are marked as such in the reference section.)

Managing objects

Summary of objects

Data attributes

Colors and color codes

Patterns and pattern codes


ΓòÉΓòÉΓòÉ 4.1. Managing objects ΓòÉΓòÉΓòÉ

These statements act on objects:

Statement               Action

CALL                    Calls an object action

LET                     Changes one of an object's attributes

MODIFY                  Allows several of an object's attributes to be changed
                        at the same time

OPEN                    Creates an instance of an object from an object class

SHUT                    Closes an instance of an object

See also .


ΓòÉΓòÉΓòÉ 4.2. Summary of objects ΓòÉΓòÉΓòÉ

Display objects

Window control objects

Graphic primitive objects

Objects for accessing data

External objects


ΓòÉΓòÉΓòÉ 4.2.1. Display objects ΓòÉΓòÉΓòÉ

These objects are used in displaying information to end users:

Object                  Description

DEFINE                  An object that is used as the parent object for
                        graphics primitives (shapes, for example)

FILEDLG                 The Presentation Manager(*) File dialog

FOLDER                  A folder like an OS/2 Workplace Shell(*) folder.

GRAPHIC                 An area in a window that you can use to display
                        graphics

IBMCHART                Application programming interface to Chart objects

IBMSQLSTATEMENT         Application programming interface to SQL statement
                        objects

IBMSQLTABLE             Application programming interface to Data viewer
                        objects

IBMREPORT               Application programming interface to Report objects

IBMTABLE                Application programming interface to Table Editor
                        objects

VIEWPORT                Used to display graphics metafiles

WINDOW                  A window


ΓòÉΓòÉΓòÉ 4.2.2. Window control objects ΓòÉΓòÉΓòÉ

These are the window control objects:

Object                  Control

CHECK                   Check box, to offer the user an on-off choice

DROPENTRY               Drop-down entry field-a single-line edit combined with
                        a selection list

DROPLIST                A selection list.

ENTRY                   Entry field (for multiline data entry)

GROUP                   Frame, with or without a title

LIST                    List box, for data in tabular form

PUSH                    Push button, to initiate an action

RADIO                   Radio button, for a multiple choice

SLE                     Single-line edit field

SCROLL                  Scroll bar (horizontal or vertical)

TBAR                    Tool bar

TEXT                    Box containing a static text string

VALUE                   Value set, for a multiple choice, using text or bit
                        maps to display the choices


ΓòÉΓòÉΓòÉ 4.2.3. Graphic primitive objects ΓòÉΓòÉΓòÉ

These are the graphic primitives that can be opened on a graphic area:

Object                  Provides

AREA                    Area in a graphic box

ARC                     Arc of a circle or ellipse

ARCPOINTS               Arc of a circle or ellipse

BITMAP                  Bit map

CIRCLE                  Circle

CURVE                   Curve

DEFINE                  A graphics object

ELLIPSE                 Ellipse

LINE                    Line or lines

OBJECT                  A group of graphic primitives

OUTLINE                 Open irregular polygon

POINT                   Marker symbol (or succession of marker symbols)

POLYGON                 Regular polygon

RECTANGLE               Rectangle

SECTOR                  Sector of circle

STRING                  Text string


ΓòÉΓòÉΓòÉ 4.2.4. Objects for accessing data ΓòÉΓòÉΓòÉ

These objects provide access to data:

Object                  Accesses

AS                      AS data and specification tables on a host system (for
                        example, a System/370(*) mainframe)

AS400SESSION            Databases on AS/400(*)

AS400TRANS              Tables in a database on AS/400

DATASESSION             Databases in general

DATATRANS               Tables in a database

HLLAPI                  Host computer systems

IBMDATA                 Table manipulation and access object

OBJECTSTORE             Data, windows, menus and programs

SQLSESSION              SQL databases, to:

   o Enquire what databases are available
   o Access a database
   o Enquire what tables and views exist
   o Control SQL Logical Units of Work
   o Use commands executable by the IMMEDIATE command of the DBM

SQLTRANS                Tables in SQL databases

SOURCECTRL              Used with direct manipulation (drag/drop)

TABLE                   User data tables

TARGETCTRL              Used with direct manipulation (drag/drop)

VIEWCALCS               Calculated columns in tables

VIEWORDER               Ordered row interface and index to tables

VIEWROWS                Multiple row interface to tables

VIEWTABLES              Table access and display object


ΓòÉΓòÉΓòÉ 4.2.5. External objects ΓòÉΓòÉΓòÉ

These objects provide access to external resources:

Object                  Accesses

CLIPBOARD               The OS/2 clipboard

DDECLIENT               The DDE object for client communication

DDESERVER               The DDE object for server communication

FILE                    OS/2 files

HELP                    The IBM Information Presentation Facility

HLLAPI                  A host system using terminal or workstation emulation
                        features

LINK                    The clipboard and DDE

MAIL                    A mail system that supports the simple messaging
                        interface (SMI) functions of the vendor-independent
                        messaging (VIM) specification

MMFILE                  Multimedia files

PRINTER                 Printers

PROFILE                 Properties of Visualizer and OS/2 (such as the current
                        date and time)

SEND                    A mail system that supports the simple messaging
                        interface (SMI) functions of the vendor-independent
                        messaging (VIM) specification

SMEMORY SFILE           These objects provide consistent input and output
                        facilities (a stream) for memory and files. The objects
                        are used with Drag/Drop, DDE, and clipboard objects.
                        (also referred to as STREAM)

SOURCECTRL              This object is used to define data rendering formats
                        for drag/drop operations

SYSTEM                  OS/2 commands, directories and files

TARGETCTRL              This object defines acceptable objects and data formats
                        for dropping (using drag/drop operations).

TIMER                   Timer with programmable alarms (TIMER events)


ΓòÉΓòÉΓòÉ 4.3. Data attributes ΓòÉΓòÉΓòÉ

CLASS attribute

PARENT attribute

Dictionary attributes

Element attributes


ΓòÉΓòÉΓòÉ 4.3.1. CLASS attribute ΓòÉΓòÉΓòÉ

Every open object has a read-only CLASS attribute, which provides the name of
the object class of the object. For instance:


OPEN SYSTEM sys
c = sys'CLASS      /* c is set to "SYSTEM" */

If the CLASS attribute is applied to a variable which is not an open object, a
NULL value is returned.


ΓòÉΓòÉΓòÉ 4.3.2. PARENT attribute ΓòÉΓòÉΓòÉ

Every open object has a read-only PARENT attribute, which provides a pointer to
its parent object, if it has one. For example:


OPEN WINDOW MyWin, ...
OPEN PUSH MyPush, MyWin, ...
LET p = MyPush'PARENT        ! p is a pointer to MyWin

The PARENT attribute is NULL for an object with no parent, or for a variable
that is not an open object.


ΓòÉΓòÉΓòÉ 4.3.3. Dictionary attributes ΓòÉΓòÉΓòÉ

Every variable has Dictionary attributes, which apply to all of its elements.
You can refer to a variable's dictionary as element zero, like this:


LET myrec[0]'TYPE="CHAR"

These are the Dictionary attributes that you can read and modify:

Read/write attribute    Meaning

TYPE                    The type of data in the variable.

   NUMERIC     Integer, decimal, or floating point

   CHARACTER   ASCII string

   DATE        Years, months, days, and periods

   TIME        Hours, minutes, seconds, and hundredths of a second

   FORMAT      A formatting string

   POINTER     Value created by the POINTER() function to provide indirect
               access to a variable

   NULL        No data type set

   GRAPHIC     DBCS string

COLOR                   Color. See  for details of colors.

FORMAT                  Format specification for NUMERIC values. (See .)

DATEFORMAT              Format specification for DATE values.

ORDER                   Scalar indicating the relative column order in a table.
                        The default is 0 which gives alphabetical ordering. If
                        two or more columns have the same numbering, they are
                        ordered alphabetically.

TIMEFORMAT              Format specification for TIME values.

WIDTH                   Display width of a column.

These are the Dictionary attributes that you can only read:

Read-only attribute     Meaning

ENTRIES                 The number of elements in an array

TABLE                   1 if the variable is a column of a table.

KEY                     The key position if the variable is a key column of a
                        table.

MODDATE                 The date when the variable was last modified. Recorded
                        only when a task ends.

MODTIME                 The time when the variable was last modified.

DIMENSIONS              One of:

   0   Scalar
   1   One-dimensional array
   2   Two-dimensional array.

LIFE                    When the variable is deleted:

   TASK      Deleted when the current task ends
   SESSION   Deleted when the session ends
   KEPT      Kept permanently in an objectstore.

ACTIVE                  1 if the variable is in use in another program.

MULTS                   The total number of elements in one row of a
                        two-dimensional array.


ΓòÉΓòÉΓòÉ 4.3.4. Element attributes ΓòÉΓòÉΓòÉ

Every element has Element attributes. You can read and modify all element
attributes except TYPE, which you can only read.

Element attribute       Meaning

TYPE                    The data type of the element.

COLOR                   Color.

FORMAT                  Format specification for NUMERIC values.

DATEFORMAT              Format specification for DATE values.

TIMEFORMAT              Format specification for TIME values.

COUNT                   Repeat count (for FORMAT values).

ELEMENT                 Element number (for POINTER values).


ΓòÉΓòÉΓòÉ 4.4. Colors and color codes ΓòÉΓòÉΓòÉ

The following colors are available. Each can be entered either as a string, or
as a code number.

Color       Code and string
Invisible    1 Invisible
Black        2 Black
Blue         3 Blue
Green        4 Green
Cyan         5 Cyan
Red          6 Red
Magenta      7 Magenta
Brown        8 Brown
White        9 White
Gray        10 Gray
Light blue  11 Lblue
Light green 12 Lgreen
Light cyan  13 Lcyan
Light red   14 Lred
Light magenta 15 Lmagenta
Yellow      16 Yellow
Bright white 17 Hiwhite
Default dialog 18
Default window 19

The color Invisible provides the same color as the window background color.

Color names can be entered in lowercase, uppercase, or any combination of the
two.


ΓòÉΓòÉΓòÉ 4.5. Patterns and pattern codes ΓòÉΓòÉΓòÉ

To specify a pattern, use a number in the range 0 - 15. The available patterns
typically look like this:


ΓòÉΓòÉΓòÉ 5. System variables ΓòÉΓòÉΓòÉ

The following variables are set by the system on entry to appropriate event
blocks.

A┬╖System┬╖Application            CHAR

                                A┬╖System┬╖Program, A┬╖System┬╖Master, and
                                A┬╖System┬╖Application are the task handles of
                                the program task that signaled the current
                                event, its master task, and its application
                                task, respectively.

A┬╖System┬╖BoxNumber              NUMERIC

                                The selected element, for example a clone or
                                row or item within a set.

                                If several items are selected, only the first
                                choice is indicated.

A┬╖System┬╖BoxValue               CHAR

                                The new value in an editable field.

A┬╖System┬╖DataPosition           NUMERIC

                                The character position of the cursor within an
                                entry field.

A┬╖System┬╖ErrorLine              NUMERIC

                                The line number in the main source file where
                                the last error occurred. If the error occurred
                                in an included file, this is the line number of
                                the @INCLUDE directive.

A┬╖System┬╖ErrorModule            CHAR

                                Name of module where last error occurred

A┬╖System┬╖ErrorInfo              CHAR

                                A vector of error information corresponding to
                                message numbers in A.System.ErrorNumber

A┬╖System┬╖ErrorNumber            CHAR

                                A vector of error numbers for the last error

A┬╖System┬╖Event                  CHAR

                                The current event name

A┬╖System┬╖Master                 CHAR

                                A┬╖System┬╖Master is the task handle of the
                                master task that started the program task that
                                signaled the current event.

A┬╖System┬╖Operation              CHAR

                                The last window sizing operation, or control
                                sizing operation, or direct manipulation
                                operation. The window sizing operations are
                                MIN, MAX, NORM, SIZE, and AUTOSELECT. The
                                control sizing operations are MOVE and SIZE.
                                The direct manipulation operations are MOVE,
                                SIZE, COPY, and AUTOREFRESH.

A┬╖System┬╖Object                 POINTER

                                Pointer to the object that signaled the current
                                event.

A┬╖System┬╖Parent                 POINTER

                                On entry to the ON START block of an ASL object
                                handler, this is a pointer to the parent
                                object.

A┬╖System┬╖PositionX              NUMERIC

                                The X position where selection took place.
                                Units relate to the object: world co-ordinates
                                for graphics, dialog units for windows.

A┬╖System┬╖PositionY              NUMERIC

                                The Y position where selection took place. Same
                                units as PositionX.

A┬╖System┬╖Program                CHAR

                                A┬╖System┬╖Program is the task handle of the
                                program task that signaled the current event.

A┬╖System┬╖Return                 UNTYPED

                                RETURN value from an event block invoked
                                directly with RUN PROGRAM.

A┬╖System┬╖Scroll                 CHAR

                                Single character indicator of scroll direction.
                                One of L, R, U, D, H, or V.

A┬╖System┬╖ScrollAmt              NUMERIC

                                Amount scrolled, 0 for one line. 1 for one
                                page. Other values indicate the slider position
                                on the slider scale.

A┬╖System┬╖StartDS                -

                                The application objectstore object handle. The
                                location attribute  A┬╖System┬╖StartDS'LOCATION
                                is the startup location of the application.

A┬╖System┬╖ThisApp                CHAR

                                Task handle of the current task's application
                                task.

A┬╖System┬╖ThisTask               CHAR

                                Task handle of the current task.

S┬╖Control┬╖Path                  CHAR

                                Location of the Visualizer system files.

                                S┬╖Control┬╖Path is equivalent to the following
                                code:


                                                                OPEN SYSTEM System
                                                                LET S.Control.Path = System'SEARCHPATH('USERLIB.A95')

S┬╖System┬╖Trace                  CHAR

                                Vector containing current trace output (if
                                trace is on).

See  for additional information on properties of the Visualizer Development and
OS/2 environments (date, date format, time, currency symbol, and language for
example).


ΓòÉΓòÉΓòÉ 6. Compilation ΓòÉΓòÉΓòÉ

The ASL compiler includes a preprocessor, which manipulates the text of a
program before compilation. The preprocessor allows you to compile sections of
the program only if certain conditions are met, substitute constant values
during compilation, and include the contents of other files. This makes it
possible to maintain a single set of source files for applications that have a
large proportion of common code.

You control the preprocessor using preprocessor directives, which all begin
with the @ character. These directives can occur anywhere in the program,
provided the @ is the first non-blank character on the line. The directives
are:

@ASSERT

@GLOBAL

@IF ... @THEN ... @ELSE ... @END

@INCLUDE

The preprocessor works in the same way regardless of whether you use the
Program editor, the Make editor, or the FTBCMP command to compile. (For an
example of using the FTBCMP command, see the FTBCOMP.CMD in the FTB1PATH
location.)

Preprocessor expressions


ΓòÉΓòÉΓòÉ 6.1. Preprocessor expressions ΓòÉΓòÉΓòÉ

Conditional compilation requires global values, which are assigned to global
variables using the @GLOBAL directive or the  -@  parameter of FTBCMP. The
names of global variables used in preprocessor directives take the form
@variable. For example, a global variable for a version number might be named
@Version. It can be set like this:

@GLOBAL @Version = 3
and tested like this:

@IF @Version > 2

The expression following @IF in the preceding example is a preprocessor
expression. A preprocessor expression can contain global variables prefixed
by @, constants, operators, and functions. There are more examples of
preprocessor expressions in the descriptions of the directives.

Global variables prefixed by @ can be used anywhere that a constant is allowed,
not just in preprocessor directives. For example:

DECLARE NUMERIC version = @Version
ERROR 1,"Welcome to Tympani Simulator version _", @Version

LET id = @Version + @Release

IF @Version = 2

Note that the values of the variables at compilation time are substituted for
the references. If a global value is not set, NULL is used.


ΓòÉΓòÉΓòÉ 6.1.1. @ASSERT ΓòÉΓòÉΓòÉ

The @ASSERT directive evaluates a preprocessor expression and produces a
compilation error if the result is false (zero) or NULL. @ASSERT can be used to
test whether required global variables have been set or whether the supplied
values are valid.


ΓòÉΓòÉΓòÉ 6.1.1.1. Format ΓòÉΓòÉΓòÉ

ΓöÇΓöÇ@ASSERTΓöÇΓöÇexpressionΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

where:

expression      is a preprocessor expression.


ΓòÉΓòÉΓòÉ 6.1.1.2. Examples ΓòÉΓòÉΓòÉ

@GLOBAL @Version = 3
...
@ASSERT @Version              ! No compilation error

@ASSERT DEFINED(@Daily) + DEFINED(@Monthly) + DEFINED(@Yearly) = 1
                              ! One and only one of these variables
                              ! must be defined to avoid an error


ΓòÉΓòÉΓòÉ 6.1.2. @GLOBAL ΓòÉΓòÉΓòÉ

The @GLOBAL directive sets a global variable.


ΓòÉΓòÉΓòÉ 6.1.2.1. Format ΓòÉΓòÉΓòÉ

ΓöÇΓöÇ@GLOBALΓöÇΓöÇ@variableΓöÇΓöÇ = ΓöÇΓöÇexpressionΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

where:

 @variable      is the name of a global variable.

expression      is a preprocessor expression. The global variable is set to the
                value of this expression.


ΓòÉΓòÉΓòÉ 6.1.2.2. Comments ΓòÉΓòÉΓòÉ

Use @GLOBAL only once for each global variable, and put all @GLOBAL directives
before any ASL code. Changing the value of an existing global variable may
produce unpredictable results. Global values can also be set using the  -@
parameter of FTBCMP.


ΓòÉΓòÉΓòÉ 6.1.2.3. Examples ΓòÉΓòÉΓòÉ

@GLOBAL @Version = 3
@GLOBAL @Yes = 1
@GLOBAL @No = \@Yes


ΓòÉΓòÉΓòÉ 6.1.3. @IF ... @THEN ... @ELSE ... @END ΓòÉΓòÉΓòÉ

The @IF directive, together with the @THEN, @ELSE, and @END directives,
controls the inclusion or exclusion of ASL code in the compilation.


ΓòÉΓòÉΓòÉ 6.1.3.1. Format ΓòÉΓòÉΓòÉ

ΓöÇΓöÇ@IFΓöÇΓöÇconditionΓöÇΓöÇΓö¼ΓöÇsourcelineΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
Γö£ΓöÇ@THENΓöÇΓöÇsourcelineΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ           ΓööΓöÇ@THENΓöÇΓöÇDOΓöÇΓöÇblockΓöÇΓöÇ@ENDΓöÇΓöÿ
ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
Γö£ΓöÇ@ELSEΓöÇΓöÇsourcelineΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ   ΓööΓöÇ@ELSEΓöÇΓöÇDOΓöÇΓöÇblockΓöÇΓöÇ@ENDΓöÇΓöÿ

where:

condition       is a preprocessor expression.

sourceline      is a line of ASL code or a preprocessor directive. A line of
                ASL code need not contain a complete ASL statement; you can
                conditionally compile parts of statements.

block           is a block of ASL statements or preprocessor directives.


ΓòÉΓòÉΓòÉ 6.1.3.2. Comments ΓòÉΓòÉΓòÉ

If the condition evaluates to true (nonzero), only the code following the
express or implied @THEN is included. If the condition evaluates to false
(zero) or NULL, only the code following the @ELSE (if supplied) is included.
Any code excluded by @IF is not passed to the compiler. This means that the
code is not even checked for syntax errors.

ASL code may not appear on the same line as @THEN or @ELSE.


ΓòÉΓòÉΓòÉ 6.1.3.3. Examples ΓòÉΓòÉΓòÉ

! Conditionally compile a block of statements
@IF @Version >= 3
@THEN DO
  OPEN DDESERVER myserver,
    APPLICATION="myappl",
    TOPIC="pippin"
  CALL myserver'FORMATS(myformats[0])
@END

! Conditionally compile part of a statement (the value of the SIZEX
! attribute of a window)
OPEN WINDOW mywin, SIZEX=
  @IF @SIZEX < 100
    100,
  @ELSE
    @SIZEX,
  SIZEY=@SIZEY

! If @Version is not already set when the following directive is
! processed, set it to 1 by default. Use the value in an ASL statement.
@IF NULL(@Version)
  @GLOBAL @Version = 1
DECLARE TASK NUMERIC Version = @Version


ΓòÉΓòÉΓòÉ 6.1.4. @INCLUDE ΓòÉΓòÉΓòÉ

The @INCLUDE directive includes the contents of a file in the compilation.


ΓòÉΓòÉΓòÉ 6.1.4.1. Format ΓòÉΓòÉΓòÉ

ΓöÇΓöÇ@INCLUDEΓöÇΓöÇfileΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

where:

file            is a preprocessor expression that evaluates to a string
                containing the identifier of the file to be included.


ΓòÉΓòÉΓòÉ 6.1.4.2. Comments ΓòÉΓòÉΓòÉ

If the file identifier does not include the location, then the compiler
searches for the file in the following locations:

 1. The current directory

 2. The directories specified on the  -I  parameters or parameters of FTBCMP

 3. The path specified by the FTB1PATH environment variable (set in the
    CONFIG┬╖SYS file).

To specify more than one path, you can use more than one  -I parameter with
FTBCMP.

The text of the included file is processed as if it appeared in the program at
the point where the @INCLUDE directive appears. The included file can contain
nested @INCLUDE directives, other directives, and ASL code. There is no
practical limit on the level of @INCLUDE nesting.

Any compilation errors generated by an included file are reported by the file
name and the line number within the file.

If the code in an included file causes a run-time error, A.System.ErrorLine
contains the line number of the @INCLUDE directive in the main source file.


ΓòÉΓòÉΓòÉ 6.1.4.3. Examples ΓòÉΓòÉΓòÉ

@INCLUDE "DDE.PGM"            ! String contains file name

@INCLUDE @Include             ! Variable contains file name

ON ERROR
  @INCLUDE "OnError.INC"      ! File contains standard code for the block


ΓòÉΓòÉΓòÉ 7. System limits ΓòÉΓòÉΓòÉ

The following limits are imposed by the system:

System limit                            Value

Significant digits in a numeric value   15

Decimal places in a numeric value       40

Characters in a string variable         255

Characters in a literal                 253

Characters in an objectstore name       20

Characters in a table or group name     20

Characters in a variable name (letters, numbers, or underscore only) 20

Dimensions in an array                  2

Elements in an array or rows in a table 64000

Key columns in a table                  16

Depth of nested parentheses in an expression 40

Depth of nested DO blocks               40

Procedures in a program                 160

Depth of nested procedure calls         80

Parameters to a CALL statement          20

Lines in a program                      16000

Maximum size of module                  64KB

Concurrently active data items          16000

Data items per objectstore              64000

Active tasks                            180

Items in a LIST object                  32767

Menu editor entries (including separators) in a pull-down menu 12

Stack sizes for C functions called from ASL (for C thread, and for calling
OS/2)                                   16KB each

Number of tables and objectstores open  63

Note:   1KB is 1024 bytes


ΓòÉΓòÉΓòÉ 8. How to read the syntax diagrams ΓòÉΓòÉΓòÉ

Throughout this book, syntax is specified with diagrams. This section describes
how to read the syntax diagrams.

o Read the syntax diagrams from left to right, from top to bottom, following
  the path of the line.

  The ΓöÇΓöÇ symbol indicates the beginning of a statement.

  The ΓöÇΓöÇ symbol indicates that the statement syntax is continued on the next
  line.

  The ΓöÇΓöÇ symbol indicates that the statement syntax is continued from the
  previous line.

  The ΓöÇ symbol indicates the end of a statement.

o Required items appear on the main path:
  ΓöÇΓöÇSTATEMENTΓöÇΓöÇrequired_itemΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

o Optional items appear below the main path:
  ΓöÇΓöÇSTATEMENTΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  ΓööΓöÇoptional_itemΓöÇΓöÿ

o If you can choose from two or more items, then they appear vertically, in a
  stack.

  If you must choose one of the items, then one item of the stack appears on
  the main path:
  ΓöÇΓöÇSTATEMENTΓöÇΓöÇΓö¼ΓöÇrequired_choice_1ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  ΓööΓöÇrequired_choice_2ΓöÇΓöÿ

  If choosing one of the items is optional, then the entire stack appears below
  the main path:
  ΓöÇΓöÇSTATEMENTΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  Γö£ΓöÇoptional_choice_1ΓöÇΓöñ         ΓööΓöÇoptional_choice_2ΓöÇΓöÿ

  If one of the optional items is the default, then it appears above the main
  path. The remaining choices are shown below:         ΓöîΓöÇdefault_choice_1ΓöÇΓöÇΓöÉ
  ΓöÇΓöÇSTATEMENTΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  Γö£ΓöÇoptional_choice_2ΓöÇΓöñ         ΓööΓöÇoptional_choice_3ΓöÇΓöÿ

o An arrow returning to the left above the main line indicates an item that you
  can repeat. Punctuation in this arrow indicates that you must insert the
  punctuation between repeated items.         ΓöîΓöÇ,ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
  Γöé
  ΓöÇΓöÇSTATEMENTΓöÇΓöÇΓöÇΓöÇrepeatable_itemΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

  A repeat arrow above a stack indicates that you can make more than one choice
  from the stacked items. (It does not mean that you can repeat a single
  choice.)        ΓöîΓöÇ,ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ               Γöé
  ΓöÇΓöÇSTATEMENTΓöÇΓöÇΓöÇΓö¼ΓöÇchoice_1ΓöÇΓö¼Γö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  ΓööΓöÇchoice_2ΓöÇΓöÿ

o Certain items can be used only if you have already used a previous item:
  ΓöÇΓöÇSTATEMENTΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  ΓööΓöÇoptional_item_1ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÿ
  ΓööΓöÇ,optional_item_2ΓöÇΓöÿ

  In this example, you can choose optional item2  only if you previously
  selected optional item1

o Keywords appear in uppercase. Spell them exactly as shown.

o Syntax variables appear in italics (for example, required_item ). They
  represent names or values that you supply.

o If the syntax diagram includes punctuation marks, parentheses, arithmetic
  operators, or such symbols, then you must enter them as part of the syntax.

o If the syntax diagram shows a series of optional parameters separated by
  commas, and you do not want to specify any of the remaining optional
  parameters, then you do not need to type the remaining commas:
  ΓöÇΓöÇFUNCTION(option1,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  ΓööΓöÇoption2ΓöÇΓöÿ  ΓööΓöÇoption3ΓöÇΓöÿ You can type:

    FUNCTION(option1)
    FUNCTION(option1,option2)

  instead of:

    FUNCTION(option1,,)
    FUNCTION(option1,option2,)


ΓòÉΓòÉΓòÉ 9. ABS() ΓòÉΓòÉΓòÉ

The ABS() function returns the absolute value of a number.

ΓöÇΓöÇABS(expression)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Examples

More about ABS()


ΓòÉΓòÉΓòÉ 9.1. Examples ΓòÉΓòÉΓòÉ

x = ABS(12-7)                !  Result is 5
x = ABS(x-11)                !  Result is 6

Examples source library:


ΓòÉΓòÉΓòÉ 9.2. More about ABS() ΓòÉΓòÉΓòÉ

o ABS returns the absolute value of expression, that is, it returns the numeric
  value whether expression is positive or negative.

o An error occurs if expression is nonnumeric and cannot be converted.


ΓòÉΓòÉΓòÉ 10. ACOS(), ACOSD() ΓòÉΓòÉΓòÉ

The ACOS() and ACOSD() functions return the angle for a given cosine.

ACOS() returns the angle in radians. ACOSD() returns the angle in degrees.

ΓöÇΓöÇACOS(cosine)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

ΓöÇΓöÇACOSD(cosine)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Examples


ΓòÉΓòÉΓòÉ 10.1. Examples ΓòÉΓòÉΓòÉ

x = ACOS(0.43)               !  Result is 1.13 (radians)
x = ACOSD(0.36)              !  Result is 68.9 (degrees)

Examples source library:


ΓòÉΓòÉΓòÉ 11. ADDWORD() ΓòÉΓòÉΓòÉ

The ADDWORD() function inserts one string into another and returns the new
string formed.

                                          ΓöîΓöÇ" "ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöÇΓöÇADDWORD(string1,string2,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ,ΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                             ΓööΓöÇnumberΓöÇΓöÿ   ΓööΓöÇseparatorΓöÇΓöÿ

Examples

More about ADDWORD()

See also: DELWORD()


ΓòÉΓòÉΓòÉ 11.1. Examples ΓòÉΓòÉΓòÉ

x = ADDWORD("at the","end")
    !  Result is "at the end"
x = ADDWORD("in middle","the",1)
    !  Result is "in the middle"
x = ADDWORD("one-two-five","three-four", 2 ,"-")
    !  Result is "one-two-three-four-five"

Examples source library:


ΓòÉΓòÉΓòÉ 11.2. More about ADDWORD() ΓòÉΓòÉΓòÉ

o ADDWORD() inserts separators between string1 and string2 to keep the
  individual words apart.

  If string2 is inserted at the start of string1, a separator is added after
  string2. If string2 is inserted in the middle of string1, a separator is
  added at both ends of string2. If string2 is added to the end of string1, an
  additional separator is inserted at the start of string2.

  Any surplus separators in string1 at the point of insertion are removed. No
  separators are removed from string2.

o An error is returned if the total length of the two strings is greater than
  the maximum string length.

o If number is greater than the number of words in string1, string2 is added to
  the end of string1 without padding spaces or separators.

o Parameters are converted if necessary.

o If number is negative, it indicates a position relative to the end of the
  string.  (For example,  -1 indicates the last item.)

o An error is returned if number is NULL. Real numbers are truncated.

o Using a string parameter of type NULL in this function produces a result of
  NULL.

o A word is defined by a combination of separators, string start and string
  end.

o If separator is omitted in a DBCS environment, an SBCS space is inserted by
  default, although DBCS spaces are assumed to be the separators used in
  string1.

o DBCS characters cannot be used as separators. However, when an SBCS space is
  specified as separator, both SBCS and DBCS spaces in string1 are recognized
  as separators.


ΓòÉΓòÉΓòÉ 12. ADJUST() ΓòÉΓòÉΓòÉ

The ADJUST() function adjusts, rounds, or truncates numeric values in various
ways.

                       ΓöîΓöÇ"NEAREST"ΓöÇΓöÉ   ΓöîΓöÇ0ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöÇΓöÇADJUST(expression,ΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇ,ΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                       ΓööΓöÇtypeΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ   ΓööΓöÇpositionΓöÇΓöÿ

Examples

See also: PRECISION


ΓòÉΓòÉΓòÉ 12.1. Examples ΓòÉΓòÉΓòÉ

x = ADJUST(1234.5)                  !  Result is 1235
x = ADJUST(56.94,"Down")            !  Result is 56
x = ADJUST(56.64,"Up",1)            !  Result is 56.7
x = ADJUST(7.919,"Truncate",2)      !  Result is 7.91
x = ADJUST(12.915,"Bankers",2)      !  Result is 12.92
x = ADJUST(94.425,"B",2)            !  Result is 94.42
x = ADJUST(-56.94,'D')              !  Result is -57
x = ADJUST(-7.919,'T',2)            !  Result is -7.91
x = ADJUST(925,,-1)                 !  Result is 930

Examples source library:


ΓòÉΓòÉΓòÉ 13. ANALYZE ΓòÉΓòÉΓòÉ

The ANALYZE statement scans one or two columns in a table, and either
accumulates counts for given value combinations, or accumulates values from a
third column.

ΓöÇΓöÇANALYZEΓöÇΓöÇresult=col1,col1valsΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                                  ΓööΓöÇ,col2,col2valsΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÿ
                                                   ΓööΓöÇ,col3sumΓöÇΓöÿ

Examples

More about ANALYZE

See also: GATHER


ΓòÉΓòÉΓòÉ 13.1. Examples ΓòÉΓòÉΓòÉ

ANALYZE could be used to find the number of men and women in each department:

ANALYZE crosstab = EmpData.Division, DivNames, EmpData.Sex, SexVals

This form of the statement would produce a two-dimensional array (called
crosstab) containing the total number of men and women working in each
specified department. SexVals would contain  "M" and "F" for men and women.
Divnames would contain a list of departments.

The example below uses the col3sum array.

! EMPDATA table should already exist and have entries like
! Name   Division    Sex  AnnualSalary
! ====== ========    ===  ============
! Andy   Production  M    10000
! Betty  Sales       F    15000
! Colin  Research    M    20000
! David  Research    M    25000
! Elsie  Research    F    30000
! Fred   Sales       M    35000
! Gill   Sales       F    40000

OPEN TABLE EmpData,
 NAME = "EmpData",
 LOCATION = system'SEARCHPATH("EmpData")
DEFINE DivNames[0]
INSERT DivNames[1] = "Research"
INSERT DivNames[2] = "Sales"
GATHER SexVals = EmpData.Sex

ANALYZE Result = EmpData.Division, Divnames,
                 EmpData.Sex, SexVals,
                 EmpData.AnnualSalary

! Result is a 2D matrix with one row for each selected
! division and one column for each sex. The value in
! each cell is the total salary for that division and sex.

!                    F       M
! Research       30000   45000
! Sales          55000   35000
! Production         0   10000

Examples source library:


ΓòÉΓòÉΓòÉ 13.2. More about ANALYZE ΓòÉΓòÉΓòÉ

o Where there is just one column of input, ANALYZE performs a similar function
  to GATHER. To see all possible row values, use the GATHER statement instead
  of ANALYZE.

o col1vals and col2vals can be obtained using the GATHER statement before
  issuing an ANALYZE statement.

o col1vals and col2vals can have their values stored in any order in the array.

o NULL values are ignored for accumulation.


ΓòÉΓòÉΓòÉ 14. ARC ΓòÉΓòÉΓòÉ

The ARC graphics primitive object class creates an instance of an arc of an
ellipse.

Parent: DEFINE

Attributes

Actions: None.

Events: None.


ΓòÉΓòÉΓòÉ 14.1. Attributes ΓòÉΓòÉΓòÉ

CLOSINGLINE            ENCLOSED
REFERENCE              TILT

The following standard graphics attributes are also available. They are
described in Standard graphics attributes:

BOUNDED                FILLCOLOR
LINEWIDTH              SELECTED
COLOR                  FILLPATTERN
MIX                    VISIBLE
CONSTANT               LINESTYLE
SELECTABLE


ΓòÉΓòÉΓòÉ 14.1.1. CLOSINGLINE ΓòÉΓòÉΓòÉ

Arc is closed with a line joining the first point to the last:

0         Arc not closed
1         Arc closed

Default: 0 (Not closed)


ΓòÉΓòÉΓòÉ 14.1.2. ENCLOSED ΓòÉΓòÉΓòÉ

Arc is treated as a closed object which can be filled:

0         Arc not enclosed
1         Arc enclosed

Default: 0 (Not enclosed)


ΓòÉΓòÉΓòÉ 14.1.3. REFERENCE ΓòÉΓòÉΓòÉ

Vector defining the arc. This vector consists of the following elements:

1         X coordinate of the center of an ellipse
2         Y coordinate of the center of an ellipse
3         X radius of the arc
4         Y radius of the arc
5         Angle (in degrees) subtended by the arc at the center of the ellipse.
          Measured counterclockwise from the start position angle.
6         Angle (in degrees) of start position of the arc, measured
          counterclockwise from the horizontal X axis

All coordinates are in world coordinate units.

Set on OPEN, then read-only.

Default: ""


ΓòÉΓòÉΓòÉ 14.1.4. TILT ΓòÉΓòÉΓòÉ

Angle at which the arc is tilted. The angle of tilt is specified in degrees and
is measured counterclockwise from the horizontal.

Default: 0 (No tilt)


ΓòÉΓòÉΓòÉ 15. ARCPOINTS ΓòÉΓòÉΓòÉ

The ARCPOINTS graphics primitive object class creates an instance of an arc of
an ellipse.

Parent: DEFINE

Attributes

Actions: None.

Events: None.


ΓòÉΓòÉΓòÉ 15.1. Attributes ΓòÉΓòÉΓòÉ

CLOSINGLINE            ENCLOSED
REFERENCE              TILT

The following standard graphics attributes are also available. They are
described in Standard graphics attributes:

BOUNDED                FILLCOLOR
LINEWIDTH              SELECTED
COLOR                  FILLPATTERN
MIX                    VISIBLE
CONSTANT               LINESTYLE
SELECTABLE


ΓòÉΓòÉΓòÉ 15.1.1. CLOSINGLINE ΓòÉΓòÉΓòÉ

Arc is closed with a line joining the first point to the last:

0         Arc not closed
1         Arc closed

Default: 0 (Not closed)


ΓòÉΓòÉΓòÉ 15.1.2. ENCLOSED ΓòÉΓòÉΓòÉ

Arc is treated as a closed object which can be filled:

0         Arc not enclosed
1         Arc enclosed

Default: 0 (Not enclosed)


ΓòÉΓòÉΓòÉ 15.1.3. REFERENCE ΓòÉΓòÉΓòÉ

Vector defining the arcpoints. This vector consists of the following elements:

1         X coordinate for the center point of the arc
2         Y coordinate for the center point of the arc
3         X radius of the arc
4         Y radius of the arc
5         X coordinate for the start point of the arc
6         Y coordinate for the start point of the arc
7         X coordinate for the end point of the arc
8         Y coordinate for the end point of the arc.

All coordinates are in world coordinate units.

The start and end points need not lie on the arc. If they do not, a line is
extended from the center point through the start or end point until it
intersects with the arc.

Set on OPEN, then read-only.

Default: ""


ΓòÉΓòÉΓòÉ 15.1.4. TILT ΓòÉΓòÉΓòÉ

Angle at which the arc is tilted. The angle of tilt is specified in degrees and
is measured counterclockwise from the horizontal.

Default: 0 (No tilt)


ΓòÉΓòÉΓòÉ 16. AREA ΓòÉΓòÉΓòÉ

The AREA graphics primitive object class defines an area in a graphic box. AREA
provides a way of linking several graphic primitives into a new shape. The
linking allows them to be treated as one primitive for purposes of coloring or
shading (for example, for three-dimensional graphics on a pie chart).

AREA differs from DEFINE in that DEFINE merely allows a group of graphic
primitives to be moved or sized together, while AREA creates a single shape.

Parent: DEFINE

Attributes

Actions: None.

Events: None.

Examples

More about AREA


ΓòÉΓòÉΓòÉ 16.1. Attributes ΓòÉΓòÉΓòÉ

CLOSINGLINE            ENCLOSED
END

The following standard graphics attributes are also available. They are
described in Standard graphics attributes:

BOUNDED                FILLPATTERN
MIX                    SELECTED
COLOR                  LINESTYLE
SELECTABLE             VISIBLE
FILLCOLOR              LINEWIDTH


ΓòÉΓòÉΓòÉ 16.1.1. CLOSINGLINE ΓòÉΓòÉΓòÉ

Whether the area is closed with a line joining the first point to the last:

0         Area not closed
1         Area closed

Default: 0 (Not closed)


ΓòÉΓòÉΓòÉ 16.1.2. ENCLOSED ΓòÉΓòÉΓòÉ

Whether the area is treated as a closed object which can be filled:

0         Area not enclosed
1         Area enclosed

Default: 0 (Not enclosed)


ΓòÉΓòÉΓòÉ 16.1.3. END ΓòÉΓòÉΓòÉ

Whether the definition of an area is complete:

0         Definition of the area not yet complete
1         Definition of the area now complete

Can be set on open. Cannot be queried.

Default: 0 (Area object not yet complete)


ΓòÉΓòÉΓòÉ 16.2. Examples ΓòÉΓòÉΓòÉ

The example below shows how to form an area from LINE and CURVE objects.

OPEN AREA area1, def1,             ! open AREA object
 CLOSINGLINE=1,                    ! AREA will be closed
 ENCLOSED=1,                       ! and enclosed, the fill
 FILLCOLOR="LBLUE"                 ! color is blue

DEFINE ARRAY[0]                    ! define array and
INSERT ARRAY[0]=10                 ! fill with line
INSERT ARRAY[0]=10                 ! end point coordinates
INSERT ARRAY[0]=250
INSERT ARRAY[0]=10
INSERT ARRAY[0]=250
INSERT ARRAY[0]=220
INSERT ARRAY[0]=250
INSERT ARRAY[0]=220
OPEN LINE line1, def1,             ! open line on define as part
 REFERENCE=ARRAY[0]                ! of area1

DEFINE ARRAY[0]                    ! define array and
INSERT ARRAY[0]=200                ! fill with curve
INSERT ARRAY[0]=100                ! parameters
INSERT ARRAY[0]=125
INSERT ARRAY[0]=260
INSERT ARRAY[0]=50
INSERT ARRAY[0]=100
OPEN CURVE curve1, def1,           ! open curve on define as part
 REFERENCE = ARRAY[0]              ! of area1
LET area1'END = 1
! Setting END means that the LINE and CURVE have now created
! a new shape which can be manipulated as area1.

Examples source library:


ΓòÉΓòÉΓòÉ 16.3. More about AREA ΓòÉΓòÉΓòÉ

o Before any graphics can be placed, a GRAPHIC area and a DEFINE must be opened
  as a base for future graphic primitives. The AREA object is opened on the
  DEFINE, then LINE objects are opened. Finally, the END attribute of the AREA
  is set to 1. This completes the definition of the AREA object. The region
  bounded by the lines can then be manipulated as if it were a single graphic
  primitive.

o The primitives ARC, CURVE, LINE, and SECTOR can be used to form an area.


ΓòÉΓòÉΓòÉ 17. AS ΓòÉΓòÉΓòÉ

The AS object provides access to IBM Application System facilities on a host
system. Host AS commands can be run, and data tables can be imported and
exported.

Attributes

Actions

Events: None.

Examples

More about AS


ΓòÉΓòÉΓòÉ 17.1. Attributes ΓòÉΓòÉΓòÉ

ASCODE                  CODE
CODEDETAIL              COLUMNS
DATEMETHOD              ERRORINFO
HOSTCODEPAGE            HOSTMESSAGE
HOSTMSGNO               KEYED
KEYS                    NAME
PROCLINE                PROCNAME
RELOBJECT               SELECT
SERVERNAME              SERVERTYPE
TIMEOUT                 TRACEAS
TRACEPC                 TRACESERVER
TYPE


ΓòÉΓòÉΓòÉ 17.1.1. ASCODE ΓòÉΓòÉΓòÉ

AS start parameters (normally the application code to be connected to). (If
ASCODE is modified, the object will attempt to end the application; if this
fails, AS will be restarted.)

Default: None


ΓòÉΓòÉΓòÉ 17.1.2. CODE ΓòÉΓòÉΓòÉ

Most recent error code.

Can be queried but not modified.

For more information on error codes, see Application System: Client Connections

Default: None


ΓòÉΓòÉΓòÉ 17.1.3. CODEDETAIL ΓòÉΓòÉΓòÉ

Return code that further defines the CODE attribute.

Can be queried but not modified.

Default: None


ΓòÉΓòÉΓòÉ 17.1.4. COLUMNS ΓòÉΓòÉΓòÉ

The COLUMNS attribute contains the total number of columns in the AS table
specified in the NAME attribute.

Can be queried but not modified

Default: None


ΓòÉΓòÉΓòÉ 17.1.5. DATEMETHOD ΓòÉΓòÉΓòÉ

The method used when exchanging date columns between host AS and Visualizer.

Set to "ISO" (default) when exchanging date columns in ISO format. Set to
"PRODUCT" when exchanging date columns in Visualizer format. The Visualizer
format causes Date columns to be written to host AS as A13 format columns, with
the Period information included in the column.

Default: "ISO"


ΓòÉΓòÉΓòÉ 17.1.6. ERRORINFO ΓòÉΓòÉΓòÉ

Error information returned from the AS object for specific CODE values. Return
codes for ERRORINFO are described in IBM Visualizer for OS/2: Installing and
Supporting Application System: Client Connections

Read-only

Default: None


ΓòÉΓòÉΓòÉ 17.1.7. HOSTCODEPAGE ΓòÉΓòÉΓòÉ

The host code page for translating data to and from Visualizer. (HOSTCODEPAGE
can be modified for SBCS code pages.)

Default: None


ΓòÉΓòÉΓòÉ 17.1.8. HOSTMESSAGE ΓòÉΓòÉΓòÉ

Latest host error message.

Can be queried but not modified.

Default: None


ΓòÉΓòÉΓòÉ 17.1.9. HOSTMSGNO ΓòÉΓòÉΓòÉ

Latest host error message number.

Can be queried but not modified.

Default: None


ΓòÉΓòÉΓòÉ 17.1.10. KEYED ΓòÉΓòÉΓòÉ

Indicates whether the table specified in the NAME attribute is keyed or is not
keyed.

0         Not keyed
1         Keyed

Read-only.

Default: None


ΓòÉΓòÉΓòÉ 17.1.11. KEYS ΓòÉΓòÉΓòÉ

Number of key columns on the mainframe table (only meaningful for KEYED
tables).

Can be queried but not modified.

Default: None


ΓòÉΓòÉΓòÉ 17.1.12. NAME ΓòÉΓòÉΓòÉ

AS name of the data or specification table.

Must be specified before using actions or attributes that refer to table
information (COLUMNS attribute or CALCOLUMNS action for example). The attribute
must be reset before each series of calls to get a table from the mainframe,
even if the value has not changed.

Default: None (When getting a table from the mainframe, NAME can be NULL; the
current AS IN table will then be used.)


ΓòÉΓòÉΓòÉ 17.1.13. PROCLINE ΓòÉΓòÉΓòÉ

The error line number, set when an AS command issued via the AS object failed
with an error creating or running an AS procedure. PROCLINE will be set to 0 if
the information is not available.

Can be queried but not modified.

Default: None


ΓòÉΓòÉΓòÉ 17.1.14. PROCNAME ΓòÉΓòÉΓòÉ

The host procedure name, set when an AS command issued via the AS object failed
with an error creating or running an AS procedure. PROCNAME will be null if the
information is not available.

Can be queried but not modified.

Default: None


ΓòÉΓòÉΓòÉ 17.1.15. RELOBJECT ΓòÉΓòÉΓòÉ

Identifier for the related Visualizer TABLE object (the table must already be
open).

Must be specified before using actions or attributes related to tables.
RELOBJECT can be reset to the handle to a new table in order to move a second
table from AS to Visualizer without closing and reopening a new AS object. The
attribute must be reset before each use, even if the value has not changed.

Default: None


ΓòÉΓòÉΓòÉ 17.1.16. SELECT ΓòÉΓòÉΓòÉ

Host AS SELECT expression to be used by the GETTABLE() Action.

Default: None


ΓòÉΓòÉΓòÉ 17.1.17. SERVERNAME ΓòÉΓòÉΓòÉ

Name of the host computer server.

SERVERNAME points to a profile entry defined in DASPWAPI.INI (see Application
System: Client Connections The profile will then have the server definition. If
no profile entry exists or DASPWAPI.INI cannot be found, SERVERTYPE is used to
determine the type of connection and SERVERNAME is used directly as the server
alias or side information name.

Set on OPEN, then read-only.

Default: None


ΓòÉΓòÉΓòÉ 17.1.18. SERVERTYPE ΓòÉΓòÉΓòÉ

The type of connection to be used when communicating with host AS (see
Application System: Client Connections

SRPI      Is the Server-Requester Programming Interface of OS/2 Communication
          Manager. The SERVERNAME attribute will be used to select the SRPI
          server alias. (SERVERNAME will point to the server details in
          DASPWAPI.INI or be used directly if no profile can be found.)
APPC      Uses the OS/2 Communications Manager CPI-C Side Information to route
          requests to the host AS partner program via APPC. The SERVERNAME
          attribute will be used to select the CPI-C side information entry.
PWSCS     Uses the Programmable Workstation Communication Services (product
          number 5684-138) to route requests to host AS. The SERVERNAME
          attribute will be used to select the PWSCS side information entry.

Set on OPEN, then read-only.

Default: The default SERVERTYPE can be defined in DASPWAPI.INI. If there is no
default type defined there, or DASPWAPI.INI cannot be found, the default type
is SRPI.


ΓòÉΓòÉΓòÉ 17.1.19. TIMEOUT ΓòÉΓòÉΓòÉ

Controls the action taken by the AS object when it finds that a SRPI server is
already in use. The TIMEOUT value is numeric:

0         The AS object should not wait, but should return immediately with the
          return code set to 9020.

>0        The number of seconds to wait for the server to become available.

<0        The wait is to be indefinite.

Set on OPEN, then read-only.

Default: 0


ΓòÉΓòÉΓòÉ 17.1.20. TRACEAS ΓòÉΓòÉΓòÉ

Initiates a DIAG SRQ trace and traces to the DASAUDIT log on the host:

0         Traceas off
1         Traceas on
If the TRACEAS attribute is used, it must be specified on the OPEN.

Default: 0 (Off)


ΓòÉΓòÉΓòÉ 17.1.21. TRACEPC ΓòÉΓòÉΓòÉ

Initiates the trace facility in the workstation environment and traces to
DASTRACE.

0         Tracepc off
1         Tracepc on

If the TRACEPC attribute is used, it must be specified on OPEN.

Default: 0 (Off)


ΓòÉΓòÉΓòÉ 17.1.22. TRACESERVER ΓòÉΓòÉΓòÉ

Initiates a function trace at the host interface:

0         Traceserver off
1         Traceserver on

The host information is written to a host dataset. On MVS, this is DASSVLOG. On
VM, it is DASSERV LOG A.

If the TRACESERVER attribute is used, it must be specified on OPEN.

Default: 0 (Off)


ΓòÉΓòÉΓòÉ 17.1.23. TYPE ΓòÉΓòÉΓòÉ

The type of the named table that is being sent to AS.

Set on OPEN TYPE must be DATA for GETTABLE or PUTTABLE actions.

Default: "DATA" (Since DATA is the default, the attribute does not need to be
set before each use.)


ΓòÉΓòÉΓòÉ 17.2. Actions ΓòÉΓòÉΓòÉ

ATTACH                   CALCOLUMNS()
CHECKSYNTAX()            COLUMNS()
COMMAND()                CREATETEMP()
CREATESVAR()             DELETESVAR()
DETAILS()                DROP()
ERRORTEXT                GETNEXTROW
GETSVAR()                GETTABLE
GOTOTOP()                KEYS()
LISTCAT()                NOKEYS()
PUTSVAR()                PUTTABLE()
RESETTABLE()             SELECT()
SETCOLUMNS()             SETKEYS()


ΓòÉΓòÉΓòÉ 17.2.1. ATTACH ΓòÉΓòÉΓòÉ

ΓöÇΓöÇATTACH(attach_parameter)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Causes the host AS to perform an ATTACH using the given parameter. This results
in the host attaching to a CDI or DB.


ΓòÉΓòÉΓòÉ 17.2.2. CALCOLUMNS() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇCALCOLUMNS(pointer)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

pointer identifies a vector of up to 20 expressions used to define new
calculated columns for the current table.

Each expression should take the following form:

 1. The basic form of the expression should follow the syntax of the host AS
    LET command for defining a new column.  The LET keyword should not be
    specified.  For example:

        NEWCOL = 100 * OLDCOL1 / OLDCOL2

 2. The new column created from Visualizer has the following default
    attributes, depending on the attributes of the expression:

   N15.      Numeric
   A24       Alphanumeric
   M9        Multiple Response
   G12       Graphic

 3. You can override the new column attributes. For example:

        ALPHA(A10) = CONCAT(COL1,'/',COL2)

    sets the length of new column ALPHA to 10 (instead of the default value,
    24).
 4. More information on host AS and the LET command can be found in Application
    System: Reference

The result from CALCOLUMNS will be 0 if no errors were detected, or will be the
row number of the failing expression. either the NAME attribute is changed or a
RESETTABLE action is performed.


ΓòÉΓòÉΓòÉ 17.2.3. CHECKSYNTAX() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇCHECKSYNTAX(command_string,type)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Causes host AS to syntax check  command_string as an AS command.  type is the
type of syntax checking to be performed and must be PROCEDURE.

If no errors are detected in the  command_string CHECKSYNTAX will return a
result of 0. If errors are detected, CHECKSYNTAX will return nonzero result
which is the offset of the error in the  command_string. The HOSTMESSAGE and
HOSTMSGNO attributes will also be set.


ΓòÉΓòÉΓòÉ 17.2.4. COLUMNS() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇCOLUMNS(asnames,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                     ΓööΓöÇasltypesΓöÇΓöÿ   ΓööΓöÇaslnamesΓöÇΓöÿ

asnames is a pointer that identifies a vector in which the names of the columns
of the table are returned. The names returned include the AS names of any
columns defined with the CALCOLUMNS action.

asltypes is an optional pointer that identifies a vector in which the type of
the columns of the table are returned. The type returned is that which
Visualizer will create for the column when the table is imported.

Column types are:

NUMERIC
CHARACTER
DATE
TIME
GRAPHIC
UNKNOWN

aslnames is an optional pointer to a vector in which the Visualizer names of
the columns are returned. The Visualizer names will be different to the AS
names if the AS name would not be valid in Visualizer.

COLUMNS is not valid for a specification table.


ΓòÉΓòÉΓòÉ 17.2.5. COMMAND() ΓòÉΓòÉΓòÉ

                            ΓöîΓöÇ0ΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöÇΓöÇCOMMAND(command_string,ΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                            ΓööΓöÇmodeΓöÇΓöÿ

COMMAND allows the direct execution of an AS command, as allowed by the AS
command interface. command_string is a valid AS command.

mode is the AS command interface terminal mode, as described in Application
System: Reference

0         AS does not use the screen.
1         Normal AS screen is displayed (if the host connection permits it).

Default: 0


ΓòÉΓòÉΓòÉ 17.2.6. CREATETEMP() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇCREATETEMP(ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                ΓööΓöÇtypeΓöÇΓöÿ

Allocates a host AS System Table and returns its name. The table will be
deleted at the end of the host AS session if it has not been used.  However, if
the table has been used for a PUTTABLE action, then it is necessary to issue a
host AS PURGE command via the COMMAND action to ensure the table is deleted.

type identifies the type of System Table to be created.  Valid values for type
are DATA and PROCEDURE. If omitted, a DATA table is created.


ΓòÉΓòÉΓòÉ 17.2.7. CREATESVAR() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇCREATESVAR(name,typesizeΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                             ΓööΓöÇ,lowsub,highsubΓöÇΓöÿ

(Application System Version 3.2 only) Creates an AS session variable.  The
variable created must meet the specification of AS session variables as created
by the AS SVARIABLES command.  More information on the SVARIABLES command can
be found in Application System: Reference

AS session variables created with CREATESVAR can be scalar or one dimensional
arrays. The type of the variable must be set.

name is the name of the AS session variable to be created.

typesize should be a character string which sets the type and size of the
session variable.  The type part is mandatory and the size part will assume a
default value if omitted.

type sets the type of the session variable and must be one of the following:

A         Alphanumeric
N         Numeric
M         Multiple Response
G         Graphic

size is the size of the session variable or the element size for the session
variable array. The size cannot exceed the maximum for its type. If no size is
specified, then AS uses the default size. The default and maximum sizes are:


 Type         Default      Maximum

 A            24           254

 N            15           15

 M            9            9

 G            12           127

If the session variable is numeric, you may specify the number of digits to the
right of the decimal point by defining the size as n.d.

The n is the total number of digits, and d is the number of digits to the right
of the decimal point. The d must be less than or equal to n. If you specify n.
any of the digits can be to the right of the decimal point. If you specify n
without a decimal, you are defining an integer session variable.

The lower and upper subscripts lowsub and highsub should either be omitted or
should both be specified. If you specify subscripts you are telling AS that you
are defining a session variable array.

lowsub defines the low subscript for a session variable array. The minimum
value is 1.

highsub defines the high subscript for a session variable array. The maximum
value is 32767.


ΓòÉΓòÉΓòÉ 17.2.8. DELETESVAR() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇDELETESVAR(name)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
(Application System Version 3.2 only) Deletes an AS session variable or deletes
all AS session variables.

name is the name of the AS session variable to be deleted or name is * to
delete all session variables.


ΓòÉΓòÉΓòÉ 17.2.9. DETAILS() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇDETAILS(pointer)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

The vector identified by pointer will be filled with details of the AS session.
The vector contains the following information:

 1. Host operating system:  MVS or VM.
 2. TSO or VM user ID.
 3. AS user ID.
 4. AS application code.
 5. SQL user ID.
 6. Character string of one or more characters indicating specification
    transfer support: C indicates charts, R indicates reports, N indicates
    network.
 7. AS version number.
 8. AS release number.
 9. AS modification level number.
10. AS Small Programming Enhancement level number.
11. AS Device code page number.
12. AS Application code page number.
13. Number of the Code page AS is running in.
14. AS National Language Support machine readable instructions codepage number.

Code page information is not available with AS Version 2 Release 2.


ΓòÉΓòÉΓòÉ 17.2.10. DROP() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇDROP(drop_parameter)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Causes the host AS to perform a DROP using the given parameter. This results in
a CDI or DB being dropped.


ΓòÉΓòÉΓòÉ 17.2.11. ERRORTEXT ΓòÉΓòÉΓòÉ

ΓöÇΓöÇERRORTEXT(pointer,msgno)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Returns the AS error message text for AS message msgno.

pointer identifies a vector to be filled with the text.


ΓòÉΓòÉΓòÉ 17.2.12. GETNEXTROW ΓòÉΓòÉΓòÉ

ΓöÇΓöÇGETNEXTROW(row_vector)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Reads the next row of data from a host AS data table and puts the values into
the vector  row_vector. For example, if four columns were selected from the
host AS table, four elements would be generated in  row_vector. The types and
formats of each element will be set to correspond to the host AS data.

The CODE attribute will be set to 0 if the vector is filled with data or to a
value of 9026 if no more data is available from the host.

The NAME attribute specifies the host AS table to be used.

While data is being read from host AS with a series of GETNEXTROW actions, most
other actions are prohibited. The series of GETNEXTROW actions must be
terminated by a RESETTABLE action or by setting the NAME attribute before other
actions can be used. The GOTOTOP action can be used within a series of
GETNEXTROW actions to restart reading of data from the beginning of the table.


ΓòÉΓòÉΓòÉ 17.2.13. GETSVAR() ΓòÉΓòÉΓòÉ

                          ΓöîΓöÇ,0ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ,0ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöÇΓöÇGETSVAR(pointer,nameΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                          Γöé          ΓöîΓöÇ0ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ  Γöé
                          ΓööΓöÇ,lowsub,ΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÿ
                                     ΓööΓöÇhighsubΓöÇΓöÿ
(Application System Version 3.2 only) gets the value of an existing AS session
variable or gets the values of a set of elements of an existing session
variable array, and places the values in an ASL variable.

The ASL variable identified by pointer is filled with the value or values of
the AS session variable. The variable will be set to either scalar or vector
according to the AS session variable.

name is the name of the AS session variable.

lowsub is the lower requested subscript for AS session variable arrays. For
scalars, this should be omitted or should be 0.

If lowsub is 0 when getting AS session variable arrays, then all elements of
the array will be returned.

highsub is the higher requested subscript for AS session variable arrays. If
lowsub is 0, then highsub should be 0 or should be omitted. If you want to get
just one element from a session variable array, this parameter may be omitted
or may be made equal to lowsub.


ΓòÉΓòÉΓòÉ 17.2.14. GETTABLE ΓòÉΓòÉΓòÉ

ΓöÇΓöÇGETTABLE()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

The rows of data for the current table and selected columns are retrieved into
variables identified by RELOBJECT. If no columns have been selected, all
columns are retrieved.

If NAME has a null value, GETTABLE will get the current AS IN table.


ΓòÉΓòÉΓòÉ 17.2.15. GOTOTOP() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇGOTOTOP()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Will restart reading from the first row of the table (used with the GETNEXTROW
action).


ΓòÉΓòÉΓòÉ 17.2.16. KEYS() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇKEYS(pointer)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

pointer identifies a vector to be filled with the names of the key columns of
the AS table. Column names are returned with a leading minus sign ( -) when the
column is in descending key sequence.


ΓòÉΓòÉΓòÉ 17.2.17. LISTCAT() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇLISTCAT(pointer,location,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                              ΓööΓöÇfilterΓöÇΓöÿ   ΓööΓöÇapplΓöÇΓöÿ

The vector identified by pointer is filled with a list of tables located in
location. The only value currently valid for location is AS.

If filter is specified, it limits the list. Valid values for filter are
APPLICATION, CHART, DATA, IN, PROCEDURE, QUERY, QS and REPORT.

APPLICATION will return a list of the Application Codes available in the
current AS session.

IN will return a list of AS tables which can be the object of the AS IN
command.

If filter is omitted, LISTCAT will return a list of DATA tables, CHART and
REPORT specification tables.

If appl is specified, the LISTCAT is run against this AS Application Code.
Otherwise, the LISTCAT refers to the catalog of the AS application code
identified by the ASCODE attribute. appl is ignored if the filter value is
APPLICATION.


ΓòÉΓòÉΓòÉ 17.2.18. NOKEYS() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇNOKEYS()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

The table is made into an unkeyed table.


ΓòÉΓòÉΓòÉ 17.2.19. PUTSVAR() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇPUTSVAR(pointer,nameΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                         ΓööΓöÇ,lowsubΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÿ
                                   ΓööΓöÇ,highsubΓöÇΓöÿ
(Application System Version 3.2 only) Updates the value of an existing AS
session variable or the values of a set of elements of an existing session
variable array from an ASL variable.

The values in the ASL variable identified by pointer are used to set the value
or values of the AS session variable.

name is the name of the existing AS session variable.

lowsub is the lower element to be set in the AS session variable array. For
scalars, this should be omitted or should be 0.

highsub is the higher element to be set in the AS session variable array. For
scalars, this should be omitted or should be 0. If you want to put just one
element to a session variable array, this parameter may be omitted or may be
made equal to lowsub.


ΓòÉΓòÉΓòÉ 17.2.20. PUTTABLE() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇPUTTABLE()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

The rows of data for the current table and selected columns are written from
variables identified by RELOBJECT and the names of previously selected columns.
If no columns have been selected, all columns are written.


ΓòÉΓòÉΓòÉ 17.2.21. RESETTABLE() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇRESETTABLE()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action will cancel all calculated columns defined by calling the
CALCOLUMNS action, all column selections made with the SETCOLUMNS action. and
all row selections defined by calling the SELECT action for the current host
table.

Note that this will not reset the SELECT attribute. This may be reset by
setting the attribute to an empty expression.


ΓòÉΓòÉΓòÉ 17.2.22. SELECT() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSELECT(select_rows)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

select_rows identifies a vector of up to 20 expressions used to select a subset
of rows from the current table.

Each expression should take the form of the parameters of the AS SELECT
command.

The result from SELECT will be 0 if no errors were detected, or will be the row
number of the failing expression.


ΓòÉΓòÉΓòÉ 17.2.23. SETCOLUMNS() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSETCOLUMNS(pVector,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                         ΓöÇ"TABLE"ΓöÇΓöñ
                        ΓööΓöÇorderΓöÇΓöÇΓöÇΓöÿ

pVector points to a vector which contains the names of the columns to be
selected from a table being used with the GETTABLE or PUTTABLE action.

order is an optional parameter which specifies the order in which the column
data is to be returned on a GETTABLE action. The SETCOLUMNS information is
reset if the NAME attribute is changed.

If order is set to TABLE or is not specified, the columns will be returned in
the same order as the host table. If order is set to VECTOR, the columns will
be returned in the order specified in the vector pointed to by pVector.


ΓòÉΓòÉΓòÉ 17.2.24. SETKEYS() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSETKEYS(pointer)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

pointer identifies a vector which contains the names of the columns which are
to become the keys of the table being written  with the PUTTABLE action. Column
names should have a leading - (minus) when the column is sequenced in
descending key order.


ΓòÉΓòÉΓòÉ 17.3. Examples ΓòÉΓòÉΓòÉ

OPEN TABLE Temp,          ! Open Table
 NAME = "HostAS",         ! Name of Table
 LOCATION = "D:\TEMP",    ! Its location
 MODE = "WRITE"           ! We want to write to it
OPEN AS Host,             ! Open a session with AS
 SERVERNAME = "DASSERV",  ! Name defined in SRPI
 ASCODE = "DEV",          ! Application Name on Host AS
 RELOBJECT = Temp,        ! Name of TABLE handle
 TYPE = "DATA",           ! Type of objects to transfer
 HOSTCODEPAGE = 285,      ! Hostpage
 NAME = "AMACK"           ! Name of AS object to transfer
CALL Host'GETTABLE()      ! Action to get Table from AS
                          ! and transfer it to TABLE temp
SHUT Temp                 ! Shut the TABLE
SHUT Host                 ! Close AS

Examples source library:


ΓòÉΓòÉΓòÉ 17.4. More about AS ΓòÉΓòÉΓòÉ

o If the SERVERTYPE is SRPI, the host server CMSSERV or MVSSERV, should be
  started on the mainframe before the host AS application is started on the PC.


ΓòÉΓòÉΓòÉ 18. AS400SESSION ΓòÉΓòÉΓòÉ

The AS/400 interface provides AS/400 access using PC Support. The AS400SESSION
object represents an AS/400 session, and the associated AS400TRANS object
represents the transfer of data to and from an AS/400 system.

With the AS400SESSION object, you can develop Visualizer applications that use
valid AS/400 commands that are passed to an AS/400 for execution. Any resulting
messages can be passed back to the Visualizer application.

Attributes

Actions

Events: None.

More about AS400SESSION

See also: AS400TRANS


ΓòÉΓòÉΓòÉ 18.1. Attributes ΓòÉΓòÉΓòÉ

CODE                  CODEDETAIL
SYSTEM                TRACELEVEL


ΓòÉΓòÉΓòÉ 18.1.1. CODE ΓòÉΓòÉΓòÉ

The latest AS/400 return code from any action or change of state. Read-only.

Default: 0 (If successful)


ΓòÉΓòÉΓòÉ 18.1.2. CODEDETAIL ΓòÉΓòÉΓòÉ

The last relevant AS/400 error message or error code.


ΓòÉΓòÉΓòÉ 18.1.3. SYSTEM ΓòÉΓòÉΓòÉ

The Partner Logical Unit (PLU) alias name for the AS/400 as defined in OS/2
Communications Manager. The name can be up to eight characters long and can be
queried, but must be set on open.


ΓòÉΓòÉΓòÉ 18.1.4. TRACELEVEL ΓòÉΓòÉΓòÉ

Whether a trace file, called FTBAS400, is produced for diagnostic purposes.

0         Tracing off
Nonzero   Tracing on

Default: 0 (Off)


ΓòÉΓòÉΓòÉ 18.2. Actions ΓòÉΓòÉΓòÉ

COMMAND()


ΓòÉΓòÉΓòÉ 18.2.1. COMMAND() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇCOMMAND(string,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                    ΓööΓöÇvectorΓöÇΓöÿ

Takes a single parameter which can be any character string value, such as a
constant, a data item, or an expression. It can also be a vector, in which case
all elements of the vector are appended to make one command string. The string
is passed to the AS/400 for immediate execution without any processing,
interpretation, or modification by Visualizer and is committed implicitly.

The optional vector parameter is used to hold any message that is returned from
the AS/400 as a result of the command previously transferred. An example of
COMMAND is shown below:

! The library must already exist
DEFINE Command[0]
INSERT Command[0] = "CRTPF FILE(LIBNAME/NEWFILE) "
INSERT Command[0] = "SRCFILE(LIBNAME/SOURCE)"
CALL Session'COMMAND(Command[0],Message[0])
    ! Pass the AS/400 command in the vector named
    ! Command to the AS/400 and place any message returned
    ! in the vector named Message.


ΓòÉΓòÉΓòÉ 18.3. More about AS400SESSION ΓòÉΓòÉΓòÉ

In order to retrieve data you must use a combination of the AS400SESSION object
(to establish communications with the AS/400), and the AS400TRANS object (to
specify the selection requests and obtain the data).

Modification of data within OS/400* or SQL/400* tables can be done in one of
two ways:

o By reading data from the OS/400 or SQL/400 table into a local table,
  modifying the data in the local table, then loading the local table to the
  AS/400 to overwrite the previous table.

o By using the Command action to send a CL command to a database on the AS/400.

You may only have one AS400SESSION object open at any one time in a Visualizer
application. Therefore concurrent access to multiple databases is not
supported.

The AS400SESSION object is the parent of any associated AS400TRANS object
instance. If the AS400SESSION object is closed, any AS400TRANS object, which is
dependent on the AS400SESSION, will also be closed. An AS400SESSION object can
only be associated with one AS400TRANS object.

The code below opens an AS/400 session:

OPEN AS400SESSION Session, SYSTEM = "as400"


ΓòÉΓòÉΓòÉ 19. AS400TRANS ΓòÉΓòÉΓòÉ

The AS400TRANS object allows you to access data in an OS/400 or SQL/400 table.
In order to open it, you must have previously opened an AS400SESSION object.
You can only have one AS400TRANS object for each AS400SESSION object.

Parent: AS400SESSION

Attributes

Actions

Events: None.

More about AS400TRANS

See also: AS400SESSION


ΓòÉΓòÉΓòÉ 19.1. Attributes ΓòÉΓòÉΓòÉ

CODE                  CODEDETAIL
EOF                   GENKEYCOL
MODE                  TABLE


ΓòÉΓòÉΓòÉ 19.1.1. CODE ΓòÉΓòÉΓòÉ

The latest return code from the AS/400 as a result of any action or change of
state. Read-only.

Default: 0 (If successful)


ΓòÉΓòÉΓòÉ 19.1.2. CODEDETAIL ΓòÉΓòÉΓòÉ

The latest relevant AS/400 error message, error code or associated explanatory
information. This code sometimes provides more detail related to the error
return in the CODE attribute. Read-only.


ΓòÉΓòÉΓòÉ 19.1.3. EOF ΓòÉΓòÉΓòÉ

EOF is set to 1 (true) when a SNAPSHOT or GETNEXTROW action can fetch no more
rows from a table. Read-only.


ΓòÉΓòÉΓòÉ 19.1.4. GENKEYCOL ΓòÉΓòÉΓòÉ

A name to be used as a key sequence. If set, an extra column will be added to
the Visualizer table generated by the SNAPSHOT action. This will be the key for
the table. If the specified name is already used in the Visualizer table, the
duplicate, existing column is renamed.

Default: No key column

trans'GENKEYCOL = "NewKS"  ! set the key sequence to NewKS

Note:   You cannot modify GENKEYCOL during a data transfer as the destination
        table for the SNAPSHOT or GETNEXTROW operation has already been
        prepared.


ΓòÉΓòÉΓòÉ 19.1.5. MODE ΓòÉΓòÉΓòÉ

The direction of data transfer for this instance of the object. Must be set on
OPEN, then read-only.

"R"       Read
"W"       Write

Default: None


ΓòÉΓòÉΓòÉ 19.1.6. TABLE ΓòÉΓòÉΓòÉ

The identity of the Visualizer table object to be used for the target table
used for a read operation or for the source table used for a write operation.
Can be modified.  For READ, this must identify an empty table with no columns
defined. For WRITE, actions use the definition of the table and its contents.
When the attribute is queried a pointer to the identity will be returned, NOT
the identity itself.

Note:   You cannot modify TABLE during data transfer.

Default: None

oldid = trans'TABLE  ! get the identity of the table object
trans'TABLE = newid  ! set the new identity


ΓòÉΓòÉΓòÉ 19.2. Actions ΓòÉΓòÉΓòÉ

GETNEXTROW()            GOTOTOP()
LOAD()                  SETEXPR()
SNAPSHOT()


ΓòÉΓòÉΓòÉ 19.2.1. GETNEXTROW() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇGETNEXTROW(ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                ΓööΓöÇvectorΓöÇΓöÿ

Reads one row resulting from the current SQL SELECT expression from a table in
an AS/400 system and places the row returned into either or both of the
following:

o An ASL vector. If the optional parameter is supplied, the values for each
  column in the resulting row are placed sequentially in the vector.

o A table specified by TABLE. The resulting row is appended to the table.

After a GETNEXTROW() action, the current query remains set, and the next row
resulting from the query becomes available for reading. If a SNAPSHOT() action
is subsequently performed, the number of the remaining rows resulting from the
current query and specified by the SNAPSHOT are read. GETNEXTROW() is valid
only in READ mode after a SETEXPR action.


ΓòÉΓòÉΓòÉ 19.2.2. GOTOTOP() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇGOTOTOP()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Resets the position of the cursor to the top of the table in the AS/400 system
from which data is being retrieved, so that a subsequent GETNEXTROW() will
deliver the first row of the table.


ΓòÉΓòÉΓòÉ 19.2.3. LOAD() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇLOAD()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Transfers the Visualizer table identified in TABLE to the AS/400 system. A
REPLACE expression must be set in SETEXPR() that includes a column list, for
example:  REPLACE col1,col2,col3 INTO tablename. If a SELECT expression is
used, the REPLACE keyword and column list are generated automatically when the
SELECT expression is delimited by exclamation marks (!), for example:

!SELECT * FROM QGPL/EMPDATA! INTO QGPL/EMPDATA

The destination table must have been previously defined on the AS/400 system so
that the number of its columns equals that of the Visualizer table, and their
data types are either the same or are convertible. This action is only valid in
WRITE mode.


ΓòÉΓòÉΓòÉ 19.2.4. SETEXPR() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSETEXPR(vector)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Takes an input expression, which can be a scalar or vector constant or
variable. The expression can also be a whole vector (vector[0]) consisting of
many strings, which are concatenated for each element. This allows complex SQL
expressions to be used for selecting data for transfer, either to or from an
AS/400. The query is given and the result becomes available for processing. If
an expression was previously set, it will discard that query and its associated
resources will be freed.

The code below specifies an SQL query:

CALL trans'SETEXPR('SELECT * FROM LIB/STAFF(STAFF1)')


ΓòÉΓòÉΓòÉ 19.2.5. SNAPSHOT() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSNAPSHOT(ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
              ΓööΓöÇnumber_of_rowsΓöÇΓöÿ

This statement maps the result of an SQL query into a Visualizer table. The
mode of the object must be READ, a valid expression must have been set, and a
valid unused Visualizer table object ID must be set in TABLE. If you specify
number_of_rows, then that number of rows is passed into the Visualizer table.
If you do not specify the number of rows, then all the rows are passed to the
table.

Data types map as follows:

AS/400    Visualizer
A         Character
B         Numeric
F         Numeric
H         Character (no direct equivalent)
P         Numeric
Date      Date
Time      Time

Name conversion is done automatically. The names of the Visualizer columns
might be changed because SQL queries do not always generate valid Visualizer
column names.

In the example below, the SQL result will be returned in the Visualizer table.

! Open AS400 Session
OPEN AS400SESSION session, SYSTEM = "AS400"
!Delete the table if it already exists
OPEN SYSTEM sys
FORGIVE
  CALL sys'DELETE("D:\TEMP\AS400.TAB")
!Open the table for write
OPEN TABLE mytab,
 NAME = "AS400.TAB",
 LOCATION = "D:\TEMP",
 MODE = "WRITE"

!Open AS400 for data access
OPEN AS400TRANS trans, session,
 TABLE = mytab,
 MODE = "R"

! Set up SELECT statement
CALL trans'SETEXPR("SELECT * FROM MLIB/EMPDATA(EMPDATA)")

CALL trans'SNAPSHOT(40)  ! retrieve the first 40 rows
CALL trans'SNAPSHOT()    ! retrieve the remaining rows
SHUT mytab
SHUT session

A subsequent call with the same code will deliver the next forty SQL result
rows. The new rows are appended to the end of the table.

Note:   You can abort a SNAPSHOT action after the operation has started by
        pressing Break while holding down the Ctrl key. A Ctrl+Break interrupts
        the SNAPSHOT action, closes the current query and resets the cursor.


ΓòÉΓòÉΓòÉ 19.3. More about AS400TRANS ΓòÉΓòÉΓòÉ

You can query a database on an AS/400 system and place the result into a
Visualizer table. Applications can place data into a table and deliver the
table objects to the AS/400 system. Applications can also use a Visualizer
table as a template for the creation of AS/400 tables.

The AS400TRANS object can have one of two modes, depending on the direction of
the transfer. The object is controlling the transfer of data either from an SQL
query to a Visualizer table (known as READ), or from a Visualizer table to an
SQL base table (known as WRITE).

The object provides the following function:

o The ability to read a whole table.

o The ability to read a number of rows (see SNAPSHOT).

o Creation of AS/400 tables using Visualizer tables as a template

o The ability to replace the contents of an AS/400 table with those of a
  Visualizer table, deleting the existing AS/400 table, and replacing it with
  the Visualizer table.

The AS400SESSION object is intended to persist over long periods, while the
AS400TRANS object is intended to be used as a disposable object (used once for
a specific transaction and then to be discarded).

The AS400SESSION object is used to control the database while AS400TRANS is
used to exchange data.

The security of data within the AS/400 databases relies on the AS/400 security.
There is no provision for direct access to the control structures used within
the interfaces.


ΓòÉΓòÉΓòÉ 20. ASIN(), ASIND() ΓòÉΓòÉΓòÉ

The ASIN() and ASIND() functions return the angle for a given sine.

The ASIN() function returns the angle in radians. The ASIND() function returns
the angle in degrees.

ΓöÇΓöÇASIN(sine)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

ΓöÇΓöÇASIND(sine)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Examples


ΓòÉΓòÉΓòÉ 20.1. Examples ΓòÉΓòÉΓòÉ

x = ASIN(0.73)               !  Result is 0.82 (radians)
x = ASIND(0.36)              !  Result is 21.1 (degrees)

Examples source library:


ΓòÉΓòÉΓòÉ 21. ATAN(), ATAND() ΓòÉΓòÉΓòÉ

The ATAN() and ATAND() functions return the angle for a given tangent.

The ATAN() function returns the angle in radians. The ATAND() function returns
the angle in degrees.

ΓöÇΓöÇATAN(tangent)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

ΓöÇΓöÇATAND(tangent)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Examples


ΓòÉΓòÉΓòÉ 21.1. Examples ΓòÉΓòÉΓòÉ

x = ATAN(1.16)               !  Result is 0.86 (radians)
x = ATAND(1.66)              !  Result is 58.93 (degrees)

Examples source library:


ΓòÉΓòÉΓòÉ 22. BITMAP ΓòÉΓòÉΓòÉ

The BITMAP graphics primitive object class displays an instance of a bit map.

Parent: DEFINE

Attributes

Actions: None.

Events: None.

Examples

See also: PUSH


ΓòÉΓòÉΓòÉ 22.1. Attributes ΓòÉΓòÉΓòÉ

BGCOLOR               BITMAP
CLASSNAME             DRAGABLE
FGCOLOR               ID
RESOURCE              SIZEX
SIZEY

The following standard graphics attributes are also available. They are
described in Standard graphics attributes:

MIX                   SELECTED
X                     Y
SELECTABLE            VISIBLE


ΓòÉΓòÉΓòÉ 22.1.1. BGCOLOR ΓòÉΓòÉΓòÉ

Overrides the background color specified in the bit map.

Valid for monochrome bit maps only.  Integer in the range 1-19. See
Colors and colorcodes for details of colors available.

Default: Color used in the window.


ΓòÉΓòÉΓòÉ 22.1.2. BITMAP ΓòÉΓòÉΓòÉ

Name of the bit map, including full path name, file name, and file extension.
Subject to system storage resources, there is no maximum size for the bit map
file. BITMAP and RESOURCE are mutually exclusive. Formats supported include
PCX, TIF, GIF, and OS/2 1.3 or 2.0 BMP.

Set on OPEN, then read-only.

Default: ""


ΓòÉΓòÉΓòÉ 22.1.3. CLASSNAME ΓòÉΓòÉΓòÉ

Name of the object class.

Default: None


ΓòÉΓòÉΓòÉ 22.1.4. DRAGABLE ΓòÉΓòÉΓòÉ

Whether the bit map can be dragged:

0         Bit map cannot be dragged
1         Bit map can be dragged.

Default: 0 (Cannot be dragged)


ΓòÉΓòÉΓòÉ 22.1.5. FGCOLOR ΓòÉΓòÉΓòÉ

Overrides the foreground color specified in the bit map.

Valid for monochrome bit maps only.  Integer in the range 1-19. See
Colors and colorcodes for details of colors available.

Default: Color used in the window.


ΓòÉΓòÉΓòÉ 22.1.6. ID ΓòÉΓòÉΓòÉ

ID number of this BITMAP from within the specified resource file.

Set on OPEN, then read-only.

Default: 0


ΓòÉΓòÉΓòÉ 22.1.7. RESOURCE ΓòÉΓòÉΓòÉ

Name of the resource (DLL) file (and path name if needed). BITMAP and RESOURCE
are mutually exclusive.

Set on OPEN, then read-only.

Default: DSS path name


ΓòÉΓòÉΓòÉ 22.1.8. SIZEX ΓòÉΓòÉΓòÉ

Size, in world coordinates.

Default: 0


ΓòÉΓòÉΓòÉ 22.1.9. SIZEY ΓòÉΓòÉΓòÉ

Size, in world coordinates.

Default: 0


ΓòÉΓòÉΓòÉ 22.2. Examples ΓòÉΓòÉΓòÉ

The example belows displays the PROGRAM bit map.

OPEN WINDOW sampwin,
 TITLE="Bitmap window",
 SIZEX=100, SIZEY=100
OPEN GRAPHIC graphbox, sampwin,
 SIZEX=50, SIZEY=50, X=25, Y=25,
 WCSMAXX=200, WCSMAXY=200
OPEN DEFINE def1, graphbox
OPEN BITMAP bmapi, def1,
 BITMAP="C:\DSS\PROG.BMP",
 SIZEX=200, SIZEY=200, X=0, Y=0

Examples source library:


ΓòÉΓòÉΓòÉ 23. BREAK ΓòÉΓòÉΓòÉ

The BREAK statement gives the programmer control over the handling of a control
break entered by an end user.

ΓöÇΓöÇBREAKΓöÇΓöÇΓö¼ΓöÇENABLEΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
           Γö£ΓöÇDISABLEΓöÇΓöÇΓöñ
           Γö£ΓöÇCHECKΓöÇΓöÇΓöÇΓöÇΓöñ
           Γö£ΓöÇCANCELΓöÇΓöÇΓöÇΓöñ
           ΓööΓöÇSIMULATEΓöÇΓöÿ

Examples

More about BREAK

See also: BREAK()


ΓòÉΓòÉΓòÉ 23.1. Examples ΓòÉΓòÉΓòÉ

ON START
DO
  BREAK ENABLE
  ...  ! Enable interruption during startup.
END

ON BREAK
DO
  IF A.System.Event = "START"
  THEN STOP
END

ON QUEUE
DO
  ...  ! Control break is disabled by default.
  BREAK ENABLE
  ...  ! Code that is to be interruptible.
  BREAK DISABLE
  ...  ! Back to code that must not be interrupted.
END

Examples source library:


ΓòÉΓòÉΓòÉ 23.2. More about BREAK ΓòÉΓòÉΓòÉ

o The system variable  A.System.Event is not set on entry to an ON BREAK block.
  It continues to indicate the event which was interrupted.

o A control break received during the system phase of START is controlled by
  the BREAK state of the calling task. If it is enabled, the start is cancelled
  and a break is signaled. If it is disabled, the program starts and the break
  can be handled by its ON START block.

o The system acknowledges receipt of the break as soon as it detects it,
  independently of the disabled state of the ASL program.

o If there is a return to the wait state without any BREAK ENABLE, the break is
  ignored (except for the message).

o The system polls for an outstanding break at certain points. The actual
  points are not precisely defined but could be, for example, the end of an
  iterative loop, the START statement, or after a MESSAGE statement.

o The following process-intensive language items can be interrupted using
  control break: ANALYZE, COPY, DELETE, INDEX, GATHER.


ΓòÉΓòÉΓòÉ 24. BREAK() ΓòÉΓòÉΓòÉ

The BREAK() function returns 1 if at least one control break is outstanding.

ΓöÇΓöÇBREAK()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Examples

More about BREAK()

See also: BREAK


ΓòÉΓòÉΓòÉ 24.1. Examples ΓòÉΓòÉΓòÉ

ON ENTER
DO
  DECLARE NUMERIC x
  BREAK DISABLE
  DO x = 1:1000000
    IF BREAK()
    THEN TERMINATE
  END
END

Examples source library:


ΓòÉΓòÉΓòÉ 24.2. More about BREAK() ΓòÉΓòÉΓòÉ

o Even though control breaks by the end user are disabled to protect data
  integrity inside a repeating DO statement, the BREAK() function allows an
  exit at a safe and convenient point in the code.


ΓòÉΓòÉΓòÉ 25. CALL ΓòÉΓòÉΓòÉ

The CALL statement calls a procedure or an object action routine. The statement
specifies the name of the procedure or action required and any parameters to be
passed to that routine.

                                <ΓöÇ,ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöÇΓöÇCALLΓöÇΓöÇΓö¼ΓöÇprocedureΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇ(ΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼Γö┤ΓöÇΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
          ΓööΓöÇobject'actionΓöÇΓöÿ      ΓööΓöÇparameterΓöÇΓöÿ

Examples

More about CALL

See also: LEAVE, LIBRARY ASL, LIBRARY DLL, LIBRARY REXX, LIBRARY ENTRY,
LIBRARY LOCAL, PROCEDURE, PROCEDURE(), RETURN

Also see the actions of specific objects.


ΓòÉΓòÉΓòÉ 25.1. Examples ΓòÉΓòÉΓòÉ


CALL Reset()
CALL main_window'REFRESH()

p = PROCEDURE('Reset')
CALL (?p)()

PROCEDURE Reset  ! No parameters
DO
  CLEAR Data
  CLEAR Totals
  NewFile = "Yes"
END

Examples source library:


ΓòÉΓòÉΓòÉ 25.2. More about CALL ΓòÉΓòÉΓòÉ

o When the requested procedure terminates, execution control is returned to the
  statement following the CALL statement.

o A procedure can be called from within another procedure.

o A procedure can be called recursively.

o A procedure can be defined in the same program, or it can be in a library
  program which is identified by the LIBRARY statement.

o On an indirect procedure call using a procedure pointer, the parameter list
  parentheses are required, even if there are no parameters. Parentheses are
  also required around the procedure reference to allow for the lower level of
  precedence of the indirection operator  ?.

o A procedure or object action can also be invoked as a function. See PROCEDURE
  for details.


ΓòÉΓòÉΓòÉ 26. CASE ... WHEN ... OTHERWISE ... END ΓòÉΓòÉΓòÉ

The CASE statement processes one of several sections of code, depending on the
value of an expression.

The WHEN statement identifies a potential value of the CASE expression. When
the expression takes on that value, the statement or statements following the
WHEN statement are executed. The TRUE, FALSE, and NULL statements perform the
function of WHEN for specific values of the expression.

The OTHERWISE statement can be placed as the last statement in a CASE construct
to introduce statements to be executed if the value of the CASE expression has
not been identified by the related WHEN clauses.

            <ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöÇΓöÇCASEΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇWHENΓöÇΓöÇlogicalexpΓöÇΓöÇstatementlistΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
          Γöé      <ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ Γöé
          ΓööΓöÇexpΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇWHENΓöÇΓöÇmatchexpΓöÇΓö¼ΓöÇΓöÇstatementlistΓöÇΓö┤ΓöÇΓöÿ
                   Γö£ΓöÇTRUEΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
                   Γö£ΓöÇFALSEΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
                   ΓööΓöÇNULLΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇENDΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
   ΓööΓöÇOTHERWISEΓöÇΓöÇstatementlistΓöÇΓöÿ

There are three forms of the CASE statement.

All three forms include several sections of code, with each section attached to
a triggering condition. Each section of code can be a single statement or
several statements enclosed by DO and END.

In the first form of the CASE statement, each section of code is preceded by
the keyword WHEN and a logical expression, logicalexp. The code following the
first logical expression that is true is processed.

The second form of CASE is used when one side of a logical expression is the
same for each section. An example would be where a variable is compared with
several possible values. Here this constant expression, exp, is compared with
each possible matching expression, matchexp, in turn. The statementlist
following the first matchexp that is equal to exp is processed.

The third form of the CASE statement allows one of three sections of code to be
processed. Depending on the result of the constant expression, exp, the
statementlist following the TRUE, FALSE, or NULL keywords is processed.

The OTHERWISE statement is optional. The OTHERWISE statement is used to process
statementlist for any values in a CASE expression which are not explicitly
identified by the preceding CASE clauses.

Examples

More about CASE ... WHEN ... OTHERWISE ... END

See also: IF ... THEN ... ELSE, IF()


ΓòÉΓòÉΓòÉ 26.1. Examples ΓòÉΓòÉΓòÉ

ON SELECT
DO
  CASE A.System.Object
    WHEN "SAVE"
      MESSAGE "FTB0001",0,"1 - Saved ..."
    WHEN "LOAD"
      MESSAGE "FTB0001",0,"1 - Loaded ..."
  END

  X = 9
  Y = 10
  CASE X < Y
    TRUE
      MESSAGE "FTB0001",0,"2 - True ..."
    FALSE
      MESSAGE "FTB0001",0,"2 - False ..."
    NULL
      MESSAGE "FTB0001",0,"2 - Null ..."
  END

  CASE
    WHEN x < y
      MESSAGE "FTB0001",0,"3 - Less ..."
    WHEN x > y
      MESSAGE "FTB0001",0,"3 - Greater ..."
    WHEN x = y
      MESSAGE "FTB0001",0,"3 - Equal ..."
  END

  CASE COMPARE( x, y )
    WHEN -1
      MESSAGE 'FTB0001',0,'4 - Less ...'
    WHEN 1
      MESSAGE 'FTB0001',0,'4 - Greater ...'
    OTHERWISE
      MESSAGE 'FTB0001",0,"4 - Equal ...'
  END

  CASE A.System.Object
    WHEN "LOAD"
      MESSAGE "FTB0001",0,"5 - Load ..."
    OTHERWISE
      MESSAGE "FTB0001",0,"5 - Otherwise"
  END

Examples source library:


ΓòÉΓòÉΓòÉ 26.2. More about CASE ... WHEN ... OTHERWISE ... END ΓòÉΓòÉΓòÉ

o The WHEN expression is executed first and the result is compared with the
  result of the CASE expression.  If no CASE expression is supplied, the WHEN
  expression is checked for being true (nonzero).

o Any number of WHEN statements can be defined for a single CASE statement.

o Only one WHEN statement is executed for a given execution of the CASE
  statement. The statement executed is the first for which the condition is
  true.

o All data types can be defined as suitable WHEN values.

o WHEN can be followed by a simple value, or by a more complex expression which
  includes operators.

o If exp is not present, any TRUE blocks, FALSE blocks, or NULL blocks are
  ignored.

o The IF statement performs a two-way test which is equivalent to
  CASE...TRUE...OTHERWISE...END. A three-way test which takes account of NULL
  values is performed by CASE...TRUE...FALSE...NULL...END.


ΓòÉΓòÉΓòÉ 27. CCHARPOS() ΓòÉΓòÉΓòÉ

The CCHARPOS() DBCS function returns the position, in a DBCS string, of the
first character of a specified word in that string.

                            ΓöîΓöÇ" "ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöÇΓöÇCCHARPOS(string,number,ΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                            ΓööΓöÇseparatorΓöÇΓöÿ

More about CCHARPOS()

See also: CHARPOS()


ΓòÉΓòÉΓòÉ 27.1. More about CCHARPOS() ΓòÉΓòÉΓòÉ

o If string is empty or contains only separators, CCHARPOS() returns zero.

o If there are fewer than number words in the string, the function returns
  zero.

o Any separator parameter must be a one-character string. DBCS characters
  cannot be used as separators.  However, when an SBCS space is specified as
  separator, both SBCS and DBCS spaces in the string are assumed to be spaces.

o Automatic conversion of parameters is carried out if necessary.

o If number is negative, it indicates a position relative to the end of the
  string. -1 indicates the last item.

o An error is returned if number is null. Real numbers are truncated.

o Using a string parameter of type NULL in this function produces a result of
  NULL.

o For the CCHARPOS() function, a word is defined by a combination of separators
  (the default is space), string start, and string end. No lexical, syntactic,
  or semantic analysis is implied.

o In most respects, CCHARPOS() behaves similarly to CHARPOS(). The difference
  is that it treats any DBCS characters in a string as single characters rather
  than as two bytes (as CHARPOS() does).


ΓòÉΓòÉΓòÉ 28. CHAR() ΓòÉΓòÉΓòÉ

The CHAR() function provides a character string from a decimal integer value.

          <ΓöÇ,ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöÇΓöÇCHAR(ΓöÇΓöÇΓöÇdinputΓöÇΓö┤ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Examples

More about CHAR()


ΓòÉΓòÉΓòÉ 28.1. Examples ΓòÉΓòÉΓòÉ

Result = CHAR(65,66)          ! Result is "AB"

Examples source library:


ΓòÉΓòÉΓòÉ 28.2. More about CHAR() ΓòÉΓòÉΓòÉ

o CHAR can be used to create a data stream (such as a file) which is in a
  specific internal format.

o If dinput is NULL, the result is NULL.


ΓòÉΓòÉΓòÉ 29. CHARPOS() ΓòÉΓòÉΓòÉ

The CHARPOS() function returns the position, in the string, of the first
character of a specified word in that string.

                           ΓöîΓöÇ" "ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöÇΓöÇCHARPOS(string,number,ΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                           ΓööΓöÇseparatorΓöÇΓöÿ

Examples

More about CHARPOS()

See also: CCHARPOS()


ΓòÉΓòÉΓòÉ 29.1. Examples ΓòÉΓòÉΓòÉ

x = CHARPOS('this that the other', 2 )              ! Result is 6
x = CHARPOS('one two three four', -1 )              ! Result is 15
x = CHARPOS('only four words here', 5 )             ! Result is 0
x = CHARPOS("martin*lucy*cathy*elizabeth*",3,"*")   ! Result is 13

Examples source library:


ΓòÉΓòÉΓòÉ 29.2. More about CHARPOS() ΓòÉΓòÉΓòÉ

o If string is empty or contains only separators, CHARPOS() returns zero.

o If there are fewer than number words in the string, the function returns
  zero.

o Any separator parameter must be a one-character string. DBCS characters
  cannot be used as separators.

o Automatic conversion of parameters is carried out if necessary.

o If number is negative, it indicates a position relative to the end of the
  string. -1 indicates the last item.

o An error is returned if number is null. Real numbers are truncated.

o Using a string parameter of type NULL in this function produces a result of
  NULL.

o For the CHARPOS() function, a word is defined by a combination of separators
  (the default is space), string start, and string end. No lexical, syntactic,
  or semantic analysis is implied.


ΓòÉΓòÉΓòÉ 30. CHECK ΓòÉΓòÉΓòÉ

The CHECK object class creates an instance of a check box.

Parent: WINDOW

Attributes

Actions

Events

Examples

More about CHECK


ΓòÉΓòÉΓòÉ 30.1. Attributes ΓòÉΓòÉΓòÉ

CHECKED               CLONEDIR
CLONEGAP              CLONES
ENABLED               EXPRESSION
HANDLES               HELP
ORIGIN                SIZEX
SIZEY                 TEXT
X                     Y
VISIBLE


ΓòÉΓòÉΓòÉ 30.1.1. CHECKED ΓòÉΓòÉΓòÉ

Whether the check box is checked:

0         Check box not checked
1         Check box checked

Default: 0 (Not checked)


ΓòÉΓòÉΓòÉ 30.1.2. CLONEDIR ΓòÉΓòÉΓòÉ

Direction in which clones are to be laid out relative to the original:

1         Down
2         Up
3         Left
4         Right

Set on OPEN, then read-only.

Default: 1 (Down)


ΓòÉΓòÉΓòÉ 30.1.3. CLONEGAP ΓòÉΓòÉΓòÉ

Gap between clones, in dialog box units.

Set on OPEN, then read-only.

Default: 0


ΓòÉΓòÉΓòÉ 30.1.4. CLONES ΓòÉΓòÉΓòÉ

Number of clones displayed.

Set on OPEN, then read-only.

Default: 1


ΓòÉΓòÉΓòÉ 30.1.5. ENABLED ΓòÉΓòÉΓòÉ

Whether the check box is enabled:

0         Check box grayed out and not selectable
1         Check box enabled

Default: 1 (Enabled)


ΓòÉΓòÉΓòÉ 30.1.6. EXPRESSION ΓòÉΓòÉΓòÉ

Pointer to a variable, the contents of which are displayed with the check box.

Note that the TEXT and EXPRESSION attributes are mutually exclusive.

Default: ""


ΓòÉΓòÉΓòÉ 30.1.7. HANDLES ΓòÉΓòÉΓòÉ

Whether sizing handles are attached to the check box to support moving, sizing,
and copying operations. These direct manipulation techniques follow the CUA
guidelines. See also the AUTOSELECT attribute of the WINDOW object.

0         Handles are not displayed
1         Handles are displayed

Default: 0 (No handles)


ΓòÉΓòÉΓòÉ 30.1.8. HELP ΓòÉΓòÉΓòÉ

Resource identifier (res ID) of the full help text for this object.

Default: 0


ΓòÉΓòÉΓòÉ 30.1.9. ORIGIN ΓòÉΓòÉΓòÉ

The corner of the enclosing window to be taken as the origin. The position of
the check box is measured from this point.

"TL"      top left
"TR"      top right
"BL"      bottom left
"BR"      bottom right

Default: "BL" (Bottom left)


ΓòÉΓòÉΓòÉ 30.1.10. SIZEX ΓòÉΓòÉΓòÉ

Width, in dialog box units.

Default: 0


ΓòÉΓòÉΓòÉ 30.1.11. SIZEY ΓòÉΓòÉΓòÉ

Height, in dialog box units.

Default: 0


ΓòÉΓòÉΓòÉ 30.1.12. TEXT ΓòÉΓòÉΓòÉ

Text to appear alongside the check box. Literal string.

Note that the TEXT and EXPRESSION attributes are mutually exclusive.

Default: ""


ΓòÉΓòÉΓòÉ 30.1.13. X ΓòÉΓòÉΓòÉ

Horizontal position within the window, in dialog box units.

Default: 0


ΓòÉΓòÉΓòÉ 30.1.14. Y ΓòÉΓòÉΓòÉ

Vertical position within the window, in dialog box units.

Default: 0


ΓòÉΓòÉΓòÉ 30.1.15. VISIBLE ΓòÉΓòÉΓòÉ

Whether the check box is displayed:

0         Check box not displayed
1         Check box displayed

Default: 1 (Displayed)


ΓòÉΓòÉΓòÉ 30.2. Actions ΓòÉΓòÉΓòÉ

REFRESH()            EDIT()


ΓòÉΓòÉΓòÉ 30.2.1. REFRESH() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇREFRESH()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Forces repainting of the check box on screen.


ΓòÉΓòÉΓòÉ 30.2.2. EDIT() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇEDIT(argument)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Enables the programmer to query whether a clipboard operation is supported and,
if it is, to carry it out.

argument is a clipboard query or a clipboard operation.

The following values for argument are used to check whether particular
clipboard operations can be supported with the check box in its current state:

"Querycut" Cut to clipboard
"Querycopy" Copy to clipboard
"Querypaste" Paste from clipboard
"Queryclear" Clear clipboard.

Where clipboard operations are supported, the following values for argument
direct them to be carried out:

"Cut"     Cut to clipboard
"Copy"    Copy to clipboard
"Paste"   Paste from clipboard
"Clear"   Clear clipboard.


ΓòÉΓòÉΓòÉ 30.3. Events ΓòÉΓòÉΓòÉ

DESKTOP            SELECT


ΓòÉΓòÉΓòÉ 30.3.1. DESKTOP ΓòÉΓòÉΓòÉ

Signaled when the check box is moved, sized, or copied. A.System.Operation is
set to "MOVE", "SIZE", or "COPY". A.System.Object contains the name of the
control.


ΓòÉΓòÉΓòÉ 30.3.2. SELECT ΓòÉΓòÉΓòÉ

Signals the ON SELECT block.

A.System.Object is set to the name of the check box. A.System.Boxnumber is set
to the clone number of the check box selected.


ΓòÉΓòÉΓòÉ 30.4. Examples ΓòÉΓòÉΓòÉ

DEFINE days[5]='Friday'            ! Every day is a Friday
OPEN check check1,win,
 X=70, Y=150, SIZEX=70, SIZEY=12,  ! position and size
 EXPRESSION="days[1]",             ! vector to use as display text
 CLONES=5, CLONEDIR=1, CLONEGAP=5  ! clone definitions

! Check boxes may be individually checked, therefore attribute set
! at individual clone level
LET check1[4]'checked=1            ! check the fourth button
LET check1[3]'enabled=0            ! gray the third button

Examples source library:


ΓòÉΓòÉΓòÉ 30.5. More about CHECK ΓòÉΓòÉΓòÉ

o The VISIBLE and HANDLES attributes can only be modified for the entire clone
  set, not for the individual clones.

o The CLONEDIR and CLONEGAP attributes can only be set at open for the entire
  clone set.


ΓòÉΓòÉΓòÉ 31. CIRCLE ΓòÉΓòÉΓòÉ

The CIRCLE graphics primitive object class creates an instance of a circle.

Parent: DEFINE

Attributes

Actions: None.

Events: None.

Examples


ΓòÉΓòÉΓòÉ 31.1. Attributes ΓòÉΓòÉΓòÉ

REFERENCE

The following standard graphics attributes are also available. They are
described in Standard graphics attributes:

BOUNDED                FILLCOLOR
LINEWIDTH              SELECTED
COLOR                  FILLPATTERN
MIX                    VISIBLE
CONSTANT               LINESTYLE
SELECTABLE


ΓòÉΓòÉΓòÉ 31.1.1. REFERENCE ΓòÉΓòÉΓòÉ

Vector defining the circle. This vector consists of the following elements:

1         X coordinate of the center of the circle
2         Y coordinate of the center of the circle
3         Radius of the circle.

All coordinates are in world coordinate units.

Set on OPEN, then read-only

Default: ""


ΓòÉΓòÉΓòÉ 31.2. Examples ΓòÉΓòÉΓòÉ

DEFINE array[3]
LET array[1]=200                ! x coord center of circle
LET array[2]=130                ! y coord center of circle
LET array[3]=100                ! radius

! open a solid circle, colored red
OPEN CIRCLE circle1, def1,
 REFERENCE = array[0],
 COLOR ="blue",                 ! color of bounding line
 FILLCOLOR ="red",              ! color of body
 FILLPATTERN =0,                ! solid
 LINESTYLE = 0,                 ! bounding line style
 LINEWIDTH = 15,                ! bounding line width
 MIX = 0,                       ! overpaint (default)
 SELECTABLE = 0,                ! not selectable (default)
 BOUNDED = 1,                   ! bounding line required (default)
 CONSTANT = 1                   ! ref array read on open (default)

Examples source library:


ΓòÉΓòÉΓòÉ 32. CLEAR ΓòÉΓòÉΓòÉ

The CLEAR statement removes all data values from a named variable. The result
is a table column of NULLs, or a nontable array or scalar with zero entries.

ΓöÇΓöÇCLEARΓöÇΓöÇvariablerefΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Examples

More about CLEAR

See also: RENAME, DELETE


ΓòÉΓòÉΓòÉ 32.1. Examples ΓòÉΓòÉΓòÉ

CLEAR Totals
CLEAR EmpData.EvalDate

Examples source library:


ΓòÉΓòÉΓòÉ 32.2. More about CLEAR ΓòÉΓòÉΓòÉ

o The name of the variable is retained in the data dictionary, as are its
  associated attributes.

o CLEAR is not valid for the key columns of a table. CLEAR on nonkey columns
  sets all values to NULLs rather than setting the number of entries to zero.
  In this way, the table has columns of equal length.

o If the variable is declared, CLEAR returns it to its initial state.


ΓòÉΓòÉΓòÉ 33. CLENGTH() ΓòÉΓòÉΓòÉ

The CLENGTH() DBCS function returns the number of characters in a variable or
the largest number of characters in any element from a range of elements in an
array. It can also be used for numeric, date, and time values.

                        ΓöîΓöÇ1ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöÇΓöÇCLENGTH(expression,ΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇ,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                        ΓööΓöÇstartΓöÇΓöÿ   ΓööΓöÇendΓöÇΓöÿ   ΓööΓöÇsepΓöÇΓöÿ

Examples

More about CLENGTH()

See also: LENGTH()


ΓòÉΓòÉΓòÉ 33.1. Examples ΓòÉΓòÉΓòÉ

String = "╞дy"             ! ╞ and д are DBCS characters
Result = CLENGTH(String)   ! Result is 3
Result = LENGTH(String)    ! Result is 5

Examples source library:


ΓòÉΓòÉΓòÉ 33.2. More about CLENGTH() ΓòÉΓòÉΓòÉ

o For a character value, the number of characters (including leading and
  trailing blanks) is returned. For numeric, date, and time values, the length
  of the character representation of the value (as defined by the FORMAT
  attribute) is given.

o DBCS characters cannot be used as separators.  However, when an SBCS space is
  specified as separator, both SBCS and DBCS trailing spaces are excluded from
  the count of characters.

o LENGTH() counts the number of bytes in a string, but CLENGTH() counts the
  number of characters in the string. Both functions give the same results in
  an SBCS environment. However, if in the variable  "Γò₧bcdefghi", Γò₧ is a DBCS
  character, then:

    x = LENGTH("Γò₧bcdefghi")   ! Result is 10
    x = CLENGTH("Γò₧bcdefghi")  ! Result is 9


ΓòÉΓòÉΓòÉ 34. CLIPBOARD ΓòÉΓòÉΓòÉ

An instance of the CLIPBOARD object gives access to the OS/2 clipboard.

The OS/2 clipboard is a place where data can be put to make it available to
another application in the system. The OS/2 clipboard can only hold the results
of one Cut or Copy at a time for any one data item. A COPY or CUT will empty
the clipboard before placing data for one object. There may be data placed onto
the clipboard (for a single item) in more than one format however.

Attributes

Actions

Events

Examples

More about CLIPBOARD

See also: DDECLIENT, DDESERVER, STREAM


ΓòÉΓòÉΓòÉ 34.1. Attributes ΓòÉΓòÉΓòÉ

OWNER


ΓòÉΓòÉΓòÉ 34.1.1. OWNER ΓòÉΓòÉΓòÉ

This Boolean attribute may be queried at any time. It returns 1 if the
application is the clipboard owner, or 0 if it is not.

Default: None


ΓòÉΓòÉΓòÉ 34.2. Actions ΓòÉΓòÉΓòÉ

DELIVER()                 EMPTY()
GET()                     LOCK()
PUT()                     QUERYFORMATS()
REGISTER()                REQUEST()
SOURCE()                  STATUS()
TARGET()                  UNLOCK()


ΓòÉΓòÉΓòÉ 34.2.1. DELIVER() ΓòÉΓòÉΓòÉ

                     ΓöîΓöÇ""ΓöÇΓöÇΓöÇΓöÉ
ΓöÇΓöÇDELIVER(Formats,ΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                     ΓööΓöÇItemΓöÇΓöÿ

This action informs the CLIPBOARD that the application wishes to render data.

Formats is a scalar or vector that names the data formats to be rendered.

Item may optionally be provided, and is a scalar that names the object for
which data is to be rendered. This value is used to set the OBJECTNAME
attribute of the SMEMORY delivered with a SOURCE event. It will be useful in
cases where an application may render data for different objects according to a
current selection. The STREAM'OBJECTNAME allows the application to understand
the context of the SOURCE event.

Only one value for Item is maintained, so the last specified value will be used
for any subsequent SOURCE events. If Item is not specified, it is set to a zero
length character string.

A SOURCE event will be generated for every format in Formats.

In order to use the DELIVER action, the client must adopt the style of opening
a CLIPBOARD and leaving it open until such time as it is not in a position to
render any more data, this would typically be at termination time.


ΓòÉΓòÉΓòÉ 34.2.2. EMPTY() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇEMPTY()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Clears the clipboard of all data, in any data format. The clipboard must be
locked using LOCK() before it can be emptied.


ΓòÉΓòÉΓòÉ 34.2.3. GET() ΓòÉΓòÉΓòÉ

                  ΓöîΓöÇ"CF_TEXT"ΓöÇΓöÉ
ΓöÇΓöÇGET(variable,ΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                  ΓööΓöÇformatΓöÇΓöÇΓöÇΓöÇΓöÿ

Returns the contents of the clipboard.

When format is "CF_TEXT", GET() can be used to access text format data. The
format parameter defaults to "CF_TEXT".

When retrieving data from the clipboard with data where format is CF_LINK data,
variable be a vector. It will be defined with three elements by the GET action,
holding the Application, Topic, and Item values. These may be assigned to the
APPLICATION and TOPIC attributes of a DDECLIENT object on OPEN to establish a
DDE conversation with the application that populated the clipboard with the
CF_LINK data. The Item value may be used as the Item parameter on various
DDECLIENT actions. If variable is a scalar, only the Application value will be
retrieved from the clipboard, no error will occur.

The clipboard must be locked using the LOCK() action before GET() is performed.

Data in the clipboard can be held in any format, but the GET and PUT actions
are limited to three formats:

o METAFILE
o TEXT
o LINK
To retrieve data from the clipboard, an application must request that data in
one of these formats. If the data does not exist on the clipboard in the format
specified, nothing can be retrieved using CLIPBOARD.

Any format can be used with the SOURCE, REGISTER, REQUEST, and DELIVER actions.
GET, PUT, and STATUS actions are available for compatibility with programs
written using earlier versions of Visualizer.


ΓòÉΓòÉΓòÉ 34.2.4. LOCK() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇLOCK()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Gives exclusive control of the clipboard to the current application. LOCK()
must be used before DELIVER, GET, PUT, QUEUE, REGISTER, REQUEST, SOURCE, or
TARGET actions. The clipboard should be kept locked for as short a time as
possible, and then freed using UNLOCK().

If the clipboard is already locked by another process, LOCK() will not return
until it is available.


ΓòÉΓòÉΓòÉ 34.2.5. PUT() ΓòÉΓòÉΓòÉ

                  ΓöîΓöÇ"CF_TEXT"ΓöÇΓöÉ
ΓöÇΓöÇPUT(variable,ΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                  ΓööΓöÇformatΓöÇΓöÇΓöÇΓöÇΓöÿ

Places the data held in variable onto the clipboard. The first PUT() operation
empties the clipboard.  Any further PUT() operations before closing the
clipboard overwrite any existing data.

format can have the values "CF_TEXT" or "CF_LINK". The format parameter
defaults to "CF_TEXT".

When format is "CF_TEXT", text format data can be placed on the clipboard using
PUT(). To put graphics data onto the clipboard, use the GRAPHIC'CLIPBOARD
action for the graphic object you want to save. You can also use the TARGET and
DELIVER actions. GET, PUT, and STATUS actions are available for compatibility
with programs written using earlier versions of Visualizer.

When populating the clipboard with data where format is CF_LINK data, variable
should be a vector with three elements holding the Application, Topic, and Item
values for the application. The PUT action will concatenate these three values,
inserting NULL (x'00') delimiters. If variable is a scalar, or a vector with
less than three elements, no error will occur, but any product pasting the data
in from the clipboard may complain with an error. If variable is a vector with
more than three elements, the excess elements are ignored.

The clipboard must be locked using the LOCK() action before a PUT() action is
performed.


ΓòÉΓòÉΓòÉ 34.2.6. QUERYFORMATS() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇQUERYFORMATS(Formats)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action may be used to obtain the data format names currently available on
the clipboard.

Formats is the name of a vector or scalar to be populated with server format
information. If the clipboard is empty, Formats will be cleared.


ΓòÉΓòÉΓòÉ 34.2.7. REGISTER() ΓòÉΓòÉΓòÉ

                      ΓöîΓöÇ""ΓöÇΓöÇΓöÇΓöÉ
ΓöÇΓöÇREGISTER(formats,ΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                      ΓööΓöÇitemΓöÇΓöÿ

This action informs the CLIPBOARD that the application is capable of rendering
data.

formats is a scalar or vector that names the data formats to be registered.

item may optionally be provided, and is a scalar that names the object for
which data may be rendered. This value is used to set the OBJECTNAME attribute
of the SMEMORY delivered with a SOURCE event. It will be useful in cases where
an application may render data for different objects according to a current
selection. The STREAM'OBJECTNAME allows the application to understand the
context of the SOURCE event.

Only one value for item is maintained, so the last specified value will be used
for any subsequent SOURCE events. If item is not specified, it is set to a zero
length character string.

A SOURCE event will be generated whenever another application requests
registered data from the clipboard.


ΓòÉΓòÉΓòÉ 34.2.8. REQUEST() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇREQUEST(Format)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action may be used to obtain data from the clipboard in the format
specified. If the specified format is not available on the clipboard, an error
condition is raised.

The REQUEST action will result in a TARGET event via which the data is
delivered to the client in the format specified.


ΓòÉΓòÉΓòÉ 34.2.9. SOURCE() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSOURCE(pStream)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action synchronously obtains data from the clipboard.

pStream is a pointer to an SMEMORY opened by the client. The CLIPBOARD object
will assume that the data to be delivered is in the format specified by the
FORMAT attribute of the SMEMORY object. If data in this format is not available
on the clipboard, an error condition is raised.

The SOURCE action will modify the MODE attribute of the STREAM depending on the
original value of MODE when the action is taken:

"READ"    MODE is set to "WRITE" prior to population with data. MODE is set to
          "READ" after population (but prior to returning to caller) and the
          POINT attribute is set to 0 (the caller can now read the data from
          the STREAM).

"READONLY" An error condition is raised

"WRITE"   The STREAM is populated with data MODE is set to "READ" after
          population (but prior to returning to caller) and the POINT attribute
          is set to 0 (the caller can now read the data from the STREAM).


ΓòÉΓòÉΓòÉ 34.2.10. STATUS() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSTATUS(ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
            ΓööΓöÇformatΓöÇΓöÿ

Returns "DATA" if there is data of format format on the clipboard. Returns
"EMPTY" if there is no data of that format on the clipboard.

If testing for the presence of text data, the format parameter must be
"CF_TEXT". If testing for graphics, the format parameter must be "CF_METAFILE"
(Otherwise, CF_LINK, CF_TEXT, or CF_METAFILE can be used.) STATUS() is retained
for compatibility with older versions of Visualizer, use QUERYFORMATS() for new
code.

format is an optional parameter. If format is omitted, the default is
"CF_TEXT".


ΓòÉΓòÉΓòÉ 34.2.11. TARGET() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇTARGET(pStream)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action synchronously populates the clipboard with the data.

pStream is a pointer to an SMEMORY opened by the client. It must have been
populated with data prior to calling the TARGET action. The CLIPBOARD object
will assume that the data is in the format specified by the FORMAT attribute of
the SMEMORY object.

If the MODE attribute of the STREAM is set to "WRITE", the TARGET action will
change MODE to "READ" before extracting the data.


ΓòÉΓòÉΓòÉ 34.2.12. UNLOCK() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇUNLOCK()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Releases the clipboard for use by other applications. UNLOCK() should be used
as soon as possible after a GET(), PUT(), or EMPTY() action.


ΓòÉΓòÉΓòÉ 34.3. Events ΓòÉΓòÉΓòÉ

SOURCE(pStream)            TARGET(pStream)
ERROR


ΓòÉΓòÉΓòÉ 34.3.1. SOURCE(pStream) ΓòÉΓòÉΓòÉ

This event occurs when the DELIVER action is invoked, or when another
application attempts to Paste in data that has been registered using the
REGISTER action. pStream is a pointer to a STREAM object delivered with the
event, through which the data may be rendered. The OBJECTNAME attribute of the
STREAM will return the value passed as the Item parameter (if any) to the
DELIVER or REGISTER action. The FORMAT attribute of the STREAM will indicate
the required data format. The MODE attribute of the STREAM will be set to
"WRITE".

When the STREAM has been populated, its FINISHED() action should be called.
This will trigger delivery of the data to the clipboard. If an error occurs
populating the STREAM, the STATUS attribute of the STREAM should be set to a
nonzero integer prior to the FINISHED() action, this will cancel the data
delivery. The STREAM should be SHUT immediately after calling the FINISHED()
action.


ΓòÉΓòÉΓòÉ 34.3.2. TARGET(pStream) ΓòÉΓòÉΓòÉ

This event occurs when the REQUEST action is invoked. pStream is a pointer to a
STREAM object delivered with the event, from which the supplied data may be
extracted. The FORMAT attribute of the STREAM will indicate the data format.
The MODE attribute of the STREAM will be set to "READONLY", and may not be
modified.

At the end of TARGET processing, the FINISHED() action of the STREAM should be
called. If errors were encountered extracting the data, the STATUS attribute of
the STREAM should be set to a nonzero number prior to the FINISHED() action.
The STREAM should be SHUT immediately after calling the FINISHED() action.


ΓòÉΓòÉΓòÉ 34.3.3. ERROR ΓòÉΓòÉΓòÉ

An error has occurred during CLIPBOARD processing. A.System.Object identifies
the CLIPBOARD object.


ΓòÉΓòÉΓòÉ 34.4. Examples ΓòÉΓòÉΓòÉ

Refer to the sample applications CLIPVIEW and CLIPSET for detailed examples of
using the clipboard object.

Examples source library:


ΓòÉΓòÉΓòÉ 34.5. More about CLIPBOARD ΓòÉΓòÉΓòÉ

o The OWNER attribute is used to check if the application is still the owner of
  the clipboard. If data has been REGISTERED for the clipboard, closing the
  application will not transfer the data. The application can warn the user to
  delay closing until the user has finished pasting data.


ΓòÉΓòÉΓòÉ 35. COMPARE() ΓòÉΓòÉΓòÉ

The COMPARE() function compares two values. It handles situations where one or
both of the values is NULL, and it provides either a three-way, or a four-way
test.

                                     ΓöîΓöÇ -1ΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöÇΓöÇCOMPARE(expression1,expression2,ΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                                     ΓööΓöÇoptionΓöÇΓöÿ

Examples

More about COMPARE()

See also: Comparisons.


ΓòÉΓòÉΓòÉ 35.1. Examples ΓòÉΓòÉΓòÉ

CASE COMPARE( x, y )
  WHEN -1
    MESSAGE 'FTB0001',0,'4 - Less ...'
  WHEN 1
    MESSAGE 'FTB0001',0,'4 - Greater ...'
  OTHERWISE
    MESSAGE 'FTB0001",0,"4 - Equal ...'
END

Examples source library:


ΓòÉΓòÉΓòÉ 35.2. More about COMPARE() ΓòÉΓòÉΓòÉ

o expression1 and expression2 can be any data type. They are converted
  according to ASL comparison rules.

o NULL values are treated as equal, unless option is 0.


ΓòÉΓòÉΓòÉ 36. COPY ΓòÉΓòÉΓòÉ

The COPY statement copies a variable. The variable copied can be either a
scalar or an array.

                           ΓöîΓöÇ1ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöÇΓöÇCOPYΓöÇΓöÇoldname,newname,ΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇ,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                           ΓööΓöÇStartElementΓöÇΓöÿ   ΓööΓöÇNumberΓöÇΓöÿ

Examples

More about COPY


ΓòÉΓòÉΓòÉ 36.1. Examples ΓòÉΓòÉΓòÉ

DECLARE NUMERIC Array1[10] = 1
DECLARE NUMERIC Array2[8]
DECLARE TASK DEFINED NULL UNTYPED Array3
COPY Array1, Array2, 1, 8    ! Copy first 8 elements
COPY Array2, Array3          ! DEFINE the result and copy the data

COPY EmpData.Name, EmpNames  ! DEFINE the result and copy the data

DEFINE Names[0]
COPY EmpNames, Names         ! Target may exist but must be empty

DEFINE Array4[10] = 3
COPY Array4, Array5, 4, 3    ! DEFINE the result and copy 3 elements

Examples source library:


ΓòÉΓòÉΓòÉ 36.2. More about COPY ΓòÉΓòÉΓòÉ

o The new reference should either not exist already, or (if it does exist)
  should contain no entries.

o Copying into a table column is valid only if the source variable contains the
  same number of values as there are rows in the table. (The source can have
  more elements than the destination if Number is used to select the same
  number of elements as the destination.


ΓòÉΓòÉΓòÉ 37. COPYTO ΓòÉΓòÉΓòÉ

The COPYTO object may be used to COPY data in a chosen format to a specified
location.

Attributes

Actions: None.

Events


ΓòÉΓòÉΓòÉ 37.1. Attributes ΓòÉΓòÉΓòÉ

OBJECTNAME             OWNERWINDOW
VISIBLE                ITEM
HELP                   FORMATS
IDENTIFIER


ΓòÉΓòÉΓòÉ 37.1.1. OBJECTNAME ΓòÉΓòÉΓòÉ

If specified, OBJECTNAME must be a character string of up to 255 bytes. This
string is used to construct the window title of the dialog. If it is not set,
the dialog title is not modified, and will remain as Copy to.

Default: None. Set on OPEN then read-only.


ΓòÉΓòÉΓòÉ 37.1.2. OWNERWINDOW ΓòÉΓòÉΓòÉ

If specified, OWNERWINDOW must be a pointer to a window handle. The referenced
window will be made the OwnerWindow of the dialog window. (See WINDOW.)

Default: None. Set on Open then read-only.


ΓòÉΓòÉΓòÉ 37.1.3. VISIBLE ΓòÉΓòÉΓòÉ

Setting it to 1 (true) surfaces the dialog.

Default: 1 (True)


ΓòÉΓòÉΓòÉ 37.1.4. ITEM ΓòÉΓòÉΓòÉ

When an SFILE is opened, the OBJECTNAME attribute of the SFILE will be
populated with the value of ITEM.

Default: ""


ΓòÉΓòÉΓòÉ 37.1.5. HELP ΓòÉΓòÉΓòÉ

If specified, the HELP numeric attribute should be set on OPEN, and should hold
the res ID for the help text for the CopyTo formats.


ΓòÉΓòÉΓòÉ 37.1.6. FORMATS ΓòÉΓòÉΓòÉ

This attribute must be a pointer to a vector of format names which include all
the formats supported by the application.

Default: None Set on Open then read-only.


ΓòÉΓòÉΓòÉ 37.1.7. IDENTIFIER ΓòÉΓòÉΓòÉ

If specified, IDENTIFIER used to set the initial file name for output files.

Default: None Set on Open then read-only.


ΓòÉΓòÉΓòÉ 37.2. Events ΓòÉΓòÉΓòÉ

QUIT              SOURCE


ΓòÉΓòÉΓòÉ 37.2.1. QUIT ΓòÉΓòÉΓòÉ

Received when the user closes the COPYTO dialog.


ΓòÉΓòÉΓòÉ 37.2.2. SOURCE ΓòÉΓòÉΓòÉ

The client's ON SOURCE block is called and passed a pointer to an SFILE. The
client is expected to populate the SFILE with the relevant data. SFILE'FORMAT
will be set to the required data format.


ΓòÉΓòÉΓòÉ 38. COS(), COSD() ΓòÉΓòÉΓòÉ

The COS() and COSD() functions return the cosine of an angle.

COS() returns the cosine value for an angle specified in radians. COSD()
returns the cosine value for an angle specified in degrees.

ΓöÇΓöÇCOS(angle)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

ΓöÇΓöÇCOSD(angle)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Examples


ΓòÉΓòÉΓòÉ 38.1. Examples ΓòÉΓòÉΓòÉ

x = COS(0.13)                !  Result is 0.99
x = COSD(68.9)               !  Result is 0.36

Examples source library:


ΓòÉΓòÉΓòÉ 39. COUNT() ΓòÉΓòÉΓòÉ

The COUNT() function returns the number of occurrences of the first non-NULL
data type encountered.

           <ΓöÇ,ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöÇΓöÇCOUNT(ΓöÇΓöÇΓöÇexpressionΓöÇΓö┤ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Examples

More about COUNT()


ΓòÉΓòÉΓòÉ 39.1. Examples ΓòÉΓòÉΓòÉ

x1 = "a"
x2 = "b"
x3 = "c"
Result = COUNT(x1,x2,x3)               ! Result is 3
Result = COUNT(x1,x2,x3,x4)            ! Result is 3
DEFINE column[5]
column[1] = 1234
column[4] = 887
Result = COUNT(column)                 ! Result is 2
Result = COUNT(x1,x2,x3,column)        ! Result is 5
Result = COUNT(column,x1,x2,x3)        ! Result is 2

Examples source library:


ΓòÉΓòÉΓòÉ 39.2. More about COUNT() ΓòÉΓòÉΓòÉ

o Numbers are automatically converted to characters while counting. Characters,
  however, are only automatically converted to numbers when they represent
  proper numeric values.


ΓòÉΓòÉΓòÉ 40. COVERLAY() ΓòÉΓòÉΓòÉ

The COVERLAY() DBCS function returns the string it is given, with part of it
replaced by another string.

There are some slight differences between OVERLAY() and COVERLAY(). These
differences are described below.

                            ΓöîΓöÇ1ΓöÇΓöÇΓöÇΓöÉ             ΓöîΓöÇ" "ΓöÇΓöÉ
ΓöÇΓöÇCOVERLAY(target,repstr,ΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇ,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ,ΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                            ΓööΓöÇnumΓöÇΓöÿ   ΓööΓöÇlenΓöÇΓöÿ   ΓööΓöÇpadΓöÇΓöÿ

Examples

OVERLAY() and COVERLAY()

More about COVERLAY()

See also: ADDWORD(), DELWORD(), OVERLAY()


ΓòÉΓòÉΓòÉ 40.1. Examples ΓòÉΓòÉΓòÉ

x = COVERLAY("1abc5","yz",3)  ! x is "1ayz5"
x = COVERLAY("1Γò₧bc5","yz",3)  ! x is "1Γò₧yz5" (Γò₧ is a DBCS character)
x = OVERLAY("1Γò₧bc5","yz",4)   ! x is "1Γò₧yz5"

Examples source library:


ΓòÉΓòÉΓòÉ 40.2. OVERLAY() and COVERLAY() ΓòÉΓòÉΓòÉ

OVERLAY() is designed for use in an SBCS environment and treats each byte as a
single character. COVERLAY() is designed for use in a DBCS environment and
manipulates DBCS characters as two-byte pairs. number and length refer to the
number of characters rather than the number of bytes. This can affect the
overlaying of the target string.


ΓòÉΓòÉΓòÉ 40.3. More about COVERLAY() ΓòÉΓòÉΓòÉ

o If repstr is positioned such that it exceeds or overlaps the length of
  target, the returned string is extended automatically. However, if the length
  of this extended string would exceed the system limit for strings, an error
  is returned.

o An error is returned if number or length is negative or NULL. Real numbers
  are truncated.

o Using a string parameter of type NULL in this function produces a result of
  NULL.

o Any pad parameter must be a one-character string.  DBCS characters cannot be
  used as pad characters.

o DBCS characters are byte pairs. This affects how COVERLAY() treats the number
  and length parameters.


ΓòÉΓòÉΓòÉ 41. CPAD() ΓòÉΓòÉΓòÉ

The CPAD() DBCS function returns a string padded up to a specified length with
a specified character.

                             ΓöîΓöÇ"L"ΓöÇΓöÇΓöÉ     ΓöîΓöÇ" "ΓöÇΓöÉ      ΓöîΓöÇ"B"ΓöÇΓöÇΓöÇΓöÉ
ΓöÇΓöÇCPAD(string,ΓöÇΓöÇlengthΓöÇΓöÇ,ΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇ,ΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇ,ΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                             ΓööΓöÇtypeΓöÇΓöÿ     ΓööΓöÇpadΓöÇΓöÿ      ΓööΓöÇstripΓöÇΓöÿ

Examples

More about CPAD()

See also: PAD()


ΓòÉΓòÉΓòÉ 41.1. Examples ΓòÉΓòÉΓòÉ

x = CPAD( "Γò₧bc", 4,, "*" )  ! x is "*Γò₧bc" (Γò₧ is a DBCS character)
x = PAD( "Γò₧bc", 5,, "*" )   ! x is "*Γò₧bc" (Γò₧ is a DBCS character)

Examples source library:


ΓòÉΓòÉΓòÉ 41.2. More about CPAD() ΓòÉΓòÉΓòÉ

o An error is returned if length is negative or null. Real numbers are
  truncated.

o length is detected by counting both SBCS and DBCS characters rather that
  bytes.

o Using a string parameter of type NULL in this function produces a result of
  NULL.

o If an odd number of characters are added, the right-hand end of the string
  gains one more character than the left.

o Only SBCS characters can be used as pad characters. DBCS characters cannot be
  used.

o If a space is specified for the strip parameter, both SBCS and DBCS spaces
  are removed.


ΓòÉΓòÉΓòÉ 42. CSCAN() ΓòÉΓòÉΓòÉ

The CSCAN() DBCS function scans for the presence or absence of one or more
specified characters in a character string. Scanning can be done from the
beginning or from the end of the string.

                                    ΓöîΓöÇ1ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ                 ΓöîΓöÇ"="ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöÇΓöÇCSCAN(expression1,expression2,ΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇ,ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇ,ΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇ
                                    ΓööΓöÇstartΓöÇΓöÿ     ΓööΓöÇendΓöÇΓöÿ     ΓööΓöÇcompareΓöÇΓöÿ
      ΓöîΓöÇ"*"ΓöÇΓöÇΓöÉ
ΓöÇΓöÇ,ΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
      ΓööΓöÇtypeΓöÇΓöÿ

Examples

More about CSCAN()

See also: SCAN()


ΓòÉΓòÉΓòÉ 42.1. Examples ΓòÉΓòÉΓòÉ

x = CSCAN( '╞дy', '╞' )   ! Result is 1 (╞ and д are DBCS characters)
x = CSCAN( '╞дy', 'д' )   ! Result is 2
x = CSCAN( '╞дy', 'y' )   ! Result is 3
x = SCAN( '╞дy', '╞' )   ! Result is 1
x = SCAN( '╞дy', 'д' )   ! Result is 3
x = SCAN( '╞дy', 'y' )   ! Result is 5

Examples source library:


ΓòÉΓòÉΓòÉ 42.2. More about CSCAN() ΓòÉΓòÉΓòÉ

o The position returned is always relative to the start (left end) of
  expression1.

o If the string expression2 is not found, CSCAN() returns a result of 0.

o CSCAN() manipulates DBCS characters as two-byte pairs. This can affect the
  points in the string at which scanning starts and stops. The start and end
  character positions are calculated by counting characters rather than bytes.

o CSCAN() works on all characters in a string. In an SBCS environment it
  behaves exactly like SCAN(), but in a DBCS environment double-byte characters
  are treated as a single character.


ΓòÉΓòÉΓòÉ 43. CSPLIT() ΓòÉΓòÉΓòÉ

The CSPLIT() DBCS function extracts part of the value of an expression.

                                                ΓöîΓöÇ" "ΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöÇΓöÇCSPLIT(expression,startpoint,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ,ΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇ,ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                                  ΓööΓöÇlengthΓöÇΓöÿ    ΓööΓöÇfillerΓöÇΓöÿ
    ΓöîΓöÇ"L"ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
    ΓööΓöÇjustifyΓöÇΓöÿ

Examples

More about CSPLIT()

See also: SPLIT()


ΓòÉΓòÉΓòÉ 43.1. Examples ΓòÉΓòÉΓòÉ

String = '╞дy чoыy'     ! ╞ д ч ы are DBCS characters
x = CSPLIT(String,2)    ! Result is 'дy чoыy'
x = CSPLIT(String,5,3)  ! Result is 'чoы'
x = SPLIT(String,3)     ! Result is 'дy чoыy'
x = SPLIT(String,7,5)   ! Result is 'чoы'

Examples source library:


ΓòÉΓòÉΓòÉ 43.2. More about CSPLIT() ΓòÉΓòÉΓòÉ

o startpoint and length refer to the number of characters, not the number of
  bytes.

o The value produced by CSPLIT() is assigned the appropriate data type.  Values
  longer than the maximum system string length are reduced to that length.

o No error is caused if positive, but not valid, values are given for
  startpoint and length. The appropriate defaults are assumed instead (a
  default of 1 is assumed for startpoint). Negative values cause an error.

o CSPLIT() manipulates DBCS characters as two-byte pairs. This can affect both
  the point in the string at which splitting starts and the length of the
  substring split off.

o Only SBCS characters can be used as filler characters with the CSPLIT()
  function. DBCS characters cannot be used.


ΓòÉΓòÉΓòÉ 44. CTRIM() ΓòÉΓòÉΓòÉ

The CTRIM() DBCS function returns a string trimmed of leading or trailing
spaces.

                  ΓöîΓöÇ"B"ΓöÇΓöÇΓöÉ
ΓöÇΓöÇCTRIM(string,ΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                  ΓööΓöÇtypeΓöÇΓöÿ

Examples

More about CTRIM()

See also: TRIM()


ΓòÉΓòÉΓòÉ 44.1. Examples ΓòÉΓòÉΓòÉ

x = CTRIM( ' ╞дy чoыy  ' )  ! x is '╞дy чoыy'

Examples source library:


ΓòÉΓòÉΓòÉ 44.2. More about CTRIM() ΓòÉΓòÉΓòÉ

o Using a string parameter of type NULL in this function produces a result of
  NULL.

o Both SBCS and DBCS spaces are removed.


ΓòÉΓòÉΓòÉ 45. CURVE ΓòÉΓòÉΓòÉ

The CURVE graphics primitive object class creates an instance of a curve.

Parent: DEFINE

Attributes

Actions: None.

Events: None.

Examples


ΓòÉΓòÉΓòÉ 45.1. Attributes ΓòÉΓòÉΓòÉ

CLOSINGLINE            ENCLOSED
REFERENCE

The following standard graphics attributes are also available. They are
described in Standard graphics attributes:

BOUNDED                FILLCOLOR
LINEWIDTH              SELECTED
COLOR                  FILLPATTERN
MIX                    VISIBLE
CONSTANT               LINESTYLE
SELECTABLE


ΓòÉΓòÉΓòÉ 45.1.1. CLOSINGLINE ΓòÉΓòÉΓòÉ

Area is closed with a line joining the first point to the last:

0         Curve not closed
1         Curve closed

Default: 0 (Not closed)


ΓòÉΓòÉΓòÉ 45.1.2. ENCLOSED ΓòÉΓòÉΓòÉ

Whether the curve is treated as a closed object which can be filled:

0         Curve not enclosed
1         Curve enclosed

Default: 0 (Not enclosed)


ΓòÉΓòÉΓòÉ 45.1.3. REFERENCE ΓòÉΓòÉΓòÉ

Vector defining the curve. This vector consists of the following elements:

1         X coordinate of the start point of the curve
2         Y coordinate of the start point of the curve
3         X coordinate of the apex point of the curve
4         Y coordinate of the apex point of the curve
5         X coordinate of the end point of the curve
6         Y coordinate of the end point of the curve.

All coordinates are in world coordinate units.

Set on OPEN, then read-only.

Default: ""


ΓòÉΓòÉΓòÉ 45.2. Examples ΓòÉΓòÉΓòÉ

! Example of use of graphic CURVE object
! Opens two samples, one a simple curve, the other enclosed.
DEFINE array[6]
LET array[1]=150                ! x start
LET array[2]=60                 ! y start
LET array[3]=80                 ! x apex
LET array[4]=120                ! y apex
LET array[5]=150                ! x end
LET array[6]=180                ! y end

OPEN CURVE curve1, def1,
 REFERENCE   = array[0],
 ENCLOSED    = 0,               ! curve not enclosable (default)
 CLOSINGLINE = 0,               ! curve not enclosed (default)
 COLOR       = 2,
 FILLCOLOR   = "Red",
 FILLPATTERN = 1,
 LINESTYLE   = 0,
 LINEWIDTH   = 1,
 CONSTANT    = 1,
 MIX         = 0,
 SELECTABLE  = 0,
 BOUNDED     = 1

! open a second curve, this time enclosed
LET array[1]=250                ! x start
LET array[2]=60                 ! y start
LET array[3]=350                ! x apex
LET array[4]=120                ! y apex
LET array[5]=250                ! x end
LET array[6]=180                ! y end
OPEN CURVE curve2, def1,
 REFERENCE   = array[0],
 ENCLOSED    = 1,               ! curve enclosable
 CLOSINGLINE = 1,               ! curve enclosed
 COLOR       = 2,
 FILLCOLOR   = "Red",
 FILLPATTERN = 1,
 LINESTYLE   = 0,
 LINEWIDTH   = 1,
 CONSTANT    = 1,
 MIX         = 0,
 SELECTABLE  = 0,
 BOUNDED     = 1

Examples source library:


ΓòÉΓòÉΓòÉ 46. CWORDPOS() ΓòÉΓòÉΓòÉ

The CWORDPOS() DBCS function returns the position of the word in a string that
contains a specified character.

                            ΓöîΓöÇ" "ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöÇΓöÇCWORDPOS(string,number,ΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                            ΓööΓöÇseparatorΓöÇΓöÿ

Examples

More about CWORDPOS()

See also: WORDPOS()


ΓòÉΓòÉΓòÉ 46.1. Examples ΓòÉΓòÉΓòÉ

x = CWORDPOS( '╞дy чoыy', 5 )  ! Result is 2
x = WORDPOS( '╞дy чoыy', 7 )   ! Result is 2

Examples source library:


ΓòÉΓòÉΓòÉ 46.2. More about CWORDPOS() ΓòÉΓòÉΓòÉ

o A zero-length string, or a string which contains nothing but separators,
  returns zero.

o If there are fewer than number characters in string, the function returns
  zero.

o Automatic conversion of parameters is carried out if necessary.

o An error is returned if number is negative or NULL. Real numbers are
  truncated.

o A string parameter of type NULL in this function produces a result of NULL.

o In this function, a word is defined by a combination of separators (the
  default is space), string start, and string end. No lexical, syntactic, or
  semantic analysis is implied.

o If the position of a separator is specified, the number of the previous word
  is returned.

o Any separator parameter used must be a string exactly one character in
  length.  No DBCS characters can be used. However, when an SBCS space is
  specified as separator, both SBCS and DBCS spaces in the string are assumed
  to be spaces.

o CWORDPOS() counts characters rather than bytes. In an SBCS environment,
  WORDPOS() and CWORDPOS() always return the same value. In a DBCS environment,
  CWORDPOS() counts DBCS characters as one while WORDPOS() counts them as two.
  In the following example, if ╨┤ is a DBCS character:


ΓòÉΓòÉΓòÉ 47. DATASESSION ΓòÉΓòÉΓòÉ

The DATASESSION object represents a connection to a database. There may be many
DATASESSION objects open concurrently, provided that the underlying databases
support this.

The connection to the database is achieved by using an interface. The only
interface supported is Q+E Database Library (QELIB). To use the DATASESSION
object, you must have QELIB installed.

Attributes

Actions

Events: None.

Examples

See also: AS400SESSION, AS400TRANS, DATATRANS, SQLSESSION, SQLTRANS.


ΓòÉΓòÉΓòÉ 47.1. Attributes ΓòÉΓòÉΓòÉ

INTERFACE             VERSION
CONNECT               DBNAME
CODE                  CODEDETAIL
REASON                TRACELEVEL
MODRECS               AUTOCOMMIT


ΓòÉΓòÉΓòÉ 47.1.1. INTERFACE ΓòÉΓòÉΓòÉ

The name of the interface used to access the database. This must be set to one
of:

"Q+E,V1"  Q+E Database Library Version 1.
"Q+E,V2"  Q+E Database Library Version 2.
"Q+E"     The highest supported release of Q+E Database Library, currently Q+E
          Database Library Version 2.


ΓòÉΓòÉΓòÉ 47.1.2. VERSION ΓòÉΓòÉΓòÉ

The version of the interface code, if the interface provides this information.


ΓòÉΓòÉΓòÉ 47.1.3. CONNECT ΓòÉΓòÉΓòÉ

The database connection string. The content of this string depends on the
database being connected, and on the interface being used.

Mandatory.


ΓòÉΓòÉΓòÉ 47.1.4. DBNAME ΓòÉΓòÉΓòÉ

The name of the default database that all subsequent SQL statements will be
sent to.

Not all database systems have this concept, so it may be mandatory, optional,
or disallowed, depending on the CONNECT.


ΓòÉΓòÉΓòÉ 47.1.5. CODE ΓòÉΓòÉΓòÉ

The interface return code from the last operation.

Mainly for query.


ΓòÉΓòÉΓòÉ 47.1.6. CODEDETAIL ΓòÉΓòÉΓòÉ

The return code from the database.

Mainly for query.


ΓòÉΓòÉΓòÉ 47.1.7. REASON ΓòÉΓòÉΓòÉ

Text that explains the most recent interface return code. Can be queried but
not modified.


ΓòÉΓòÉΓòÉ 47.1.8. TRACELEVEL ΓòÉΓòÉΓòÉ

Whether a trace file is produced for diagnostic purposes.

0         Tracing off
Nonzero   Tracing on

The name of the trace file for the Q+E interface is FTBDATQE.

Default: 0 (Off)


ΓòÉΓòÉΓòÉ 47.1.9. MODRECS ΓòÉΓòÉΓòÉ

The number of records modified by the last INSERT, UPDATE, or DELETE.


ΓòÉΓòÉΓòÉ 47.1.10. AUTOCOMMIT ΓòÉΓòÉΓòÉ

If this is set to 1, a COMMIT() is done for open transactions when they are
implicitly, closed, either by the start of another transaction or by the
shutting of the object. If it is set to 0, ROLLBACK() is done instead.

Default: 0


ΓòÉΓòÉΓòÉ 47.2. Actions ΓòÉΓòÉΓòÉ

COMMAND()                TRANSACTION()
COMMIT()                 ROLLBACK()


ΓòÉΓòÉΓòÉ 47.2.1. COMMAND() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇCOMMAND(command,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                     ΓööΓöÇmessageΓöÇΓöÿ

Execute an arbitrary SQL command. SQL parameterised commands are not supported.

command   This is a scalar, or a whole vector indicated by [0], containing the
          command to be executed.

message   This is a scalar, or a whole vector indicated by [0], which will
          receive any messages from the command.


ΓòÉΓòÉΓòÉ 47.2.2. TRANSACTION() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇTRANSACTION()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Starts a new transaction on the database connection.


ΓòÉΓòÉΓòÉ 47.2.3. COMMIT() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇCOMMIT()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Commit all changes and end the transaction.


ΓòÉΓòÉΓòÉ 47.2.4. ROLLBACK() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇROLLBACK()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Rollback all changes and end the transaction.


ΓòÉΓòÉΓòÉ 47.3. Examples ΓòÉΓòÉΓòÉ

For examples, see DATATRANS.

Examples source library:


ΓòÉΓòÉΓòÉ 48. DATATRANS ΓòÉΓòÉΓòÉ

The DATATRANS object represents data transfer to or from a database which is
being accessed through a DATASESSION object. The DATATRANS must be opened with
a DATASESSION as its parent.

Attributes

Actions

Events: None.

Examples

See also: AS400SESSION, AS400TRANS, DATASESSION, SQLSESSION, SQLTRANS.


ΓòÉΓòÉΓòÉ 48.1. Attributes ΓòÉΓòÉΓòÉ

ACCESS                CODE
CODEDETAIL            REASON
TABLE                 COLUMNS
GENKEYCOL             TRIM
EOF


ΓòÉΓòÉΓòÉ 48.1.1. ACCESS ΓòÉΓòÉΓòÉ

Sets the database access mode to either "SEQUENTIAL" or "RANDOM". (You can
abbreviate these to one character.)

Default "SEQUENTIAL", which limits data access to GETNEXTROW() and SNAPSHOT().


ΓòÉΓòÉΓòÉ 48.1.2. CODE ΓòÉΓòÉΓòÉ

The interface return code from the last operation.


ΓòÉΓòÉΓòÉ 48.1.3. CODEDETAIL ΓòÉΓòÉΓòÉ

The return code from the database.


ΓòÉΓòÉΓòÉ 48.1.4. REASON ΓòÉΓòÉΓòÉ

Text that explains the most recent interface return code. Can be queried but
not modified.


ΓòÉΓòÉΓòÉ 48.1.5. TABLE ΓòÉΓòÉΓòÉ

Associates a Product table with the transfer.


ΓòÉΓòÉΓòÉ 48.1.6. COLUMNS ΓòÉΓòÉΓòÉ

The number of columns present in a SELECT statement.


ΓòÉΓòÉΓòÉ 48.1.7. GENKEYCOL ΓòÉΓòÉΓòÉ

Names a column that is to be added to the table as a generated key column. The
column contains ascending integers.


ΓòÉΓòÉΓòÉ 48.1.8. TRIM ΓòÉΓòÉΓòÉ

Whether all character strings read from the database have trailing blanks
removed.

0         Trailing blanks not removed
1         Trailing blanks removed

Default: 0 (Trailing blanks not removed)


ΓòÉΓòÉΓòÉ 48.1.9. EOF ΓòÉΓòÉΓòÉ

Set to 1 (true) if the last data retrieval resulted in End Of Fetch.


ΓòÉΓòÉΓòÉ 48.2. Actions ΓòÉΓòÉΓòÉ

GOTOTOP()               SNAPSHOT()
SETEXPR()               SQLTABLE()
COLUMNS()               SETKEYS()
KEYS()                  GETNEXTROW()
GETPREVROW()            GETROW()
LOAD()


ΓòÉΓòÉΓòÉ 48.2.1. GOTOTOP() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇGOTOTOP()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
Reset retrieval so that the next row fetched will be the first row.


ΓòÉΓòÉΓòÉ 48.2.2. SNAPSHOT() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSNAPSHOT(ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
              ΓööΓöÇcountΓöÇΓöÿ
Fetch the next sequential rows and add them to the associated Product table.

count     The maximum number of rows to retrieve. If omitted, the whole table
          is retrieved.

Requires ACCESS="SEQ"


ΓòÉΓòÉΓòÉ 48.2.3. SETEXPR() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSETEXPR(expression)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
Sets up an SQL SELECT expression which defines a query for later retrieval.
Parameterised expressions are not supported.

expr      This is a scalar, or a whole vector indicated by [0], containing the
          SELECT expression. Vector elements are concatenated with no
          intervening separators, so required blanks must be included in the
          input.


ΓòÉΓòÉΓòÉ 48.2.4. SQLTABLE() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSQLTABLE(sqltable)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

For LOAD(), SQLTABLE() names the table to be loaded.

For GET, SQLTABLE(x) is shorthand for SETEXPR("SELECT * FROM x").

sqltable  This is a scalar naming the SQL table.


ΓòÉΓòÉΓòÉ 48.2.5. COLUMNS() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇCOLUMNS(names,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                   ΓööΓöÇtypesΓöÇΓöÿ
The names of the columns present in a SELECT statement.

The column names in a table are passed through the existing name filter to
ensure that the set of names is suitable for a Product table. This involves:

o Replacing unacceptable characters by underscores
o Resolving duplicates by adding a unique numeric suffix
o Supplying a default name, "SQL" plus a suffix, for any column which has no
  name, or whose name is wholly unacceptable.

names     The column names
types     The column types


ΓòÉΓòÉΓòÉ 48.2.6. SETKEYS() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSETKEYS(keyvector)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
Identifies the columns to be used as keys when data is loaded into a Product
table. If this is not specified, the key will be a generated key column called
SEQKEY.

keyvector A vector containing the names of the key columns, in major-to-minor
          order.


ΓòÉΓòÉΓòÉ 48.2.7. KEYS() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇKEYS(keyvector)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
Returns the columns which will be used as keys.

KEYS( vector )

keyvector A vector to be filled with the names of the key columns, in
          major-to-minor order.


ΓòÉΓòÉΓòÉ 48.2.8. GETNEXTROW() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇGETNEXTROW(ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                ΓööΓöÇvectorΓöÇΓöÿ

Fetch the next sequential row and place the column elements into a vector (if
specified), and add the row to the associated Product table (if available).

vector    If specified, the column elements are placed in this vector. If it is
          omitted, the column elements are associated with like-named columns
          in the associated Product table and the values are used to insert a
          new row.

Requires ACCESS="SEQ".


ΓòÉΓòÉΓòÉ 48.2.9. GETPREVROW() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇGETPREVROW(ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                ΓööΓöÇvectorΓöÇΓöÿ

Fetch the previous row and place the column elements into a vector (if
specified), and add the row to the associated Product table (if available).

vector    If specified, the column elements are placed in this vector. If it is
          omitted, the column elements are associated with like-named columns
          in the associated Product table and the values are used to insert a
          new row.

Requires ACCESS="RANDOM".


ΓòÉΓòÉΓòÉ 48.2.10. GETROW() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇGETROW(ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ,rownumber)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
            ΓööΓöÇvectorΓöÇΓöÿ

Fetch a specific row and place the column elements into a vector (if
specified), and add the row to the associated Product table (if available).

vector    If specified, the column elements are placed in this vector. If it is
          omitted, the column elements are associated with like-named columns
          in the associated Product table and the values are used to insert a
          new row.

rownumber The number of the row to be retrieved.

Requires ACCESS="RANDOM".


ΓòÉΓòÉΓòÉ 48.2.11. LOAD() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇLOAD(ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
          ΓööΓöÇfirstΓöÇΓöÿ   ΓööΓöÇlastΓöÇΓöÿ
Load rows from the associated Product table into the database.

first     The index of the first row to be used. If it is omitted, processing
          starts at the first row of the table.

last      The index of the last row to be used. If it is omitted, processing
          ends at the last row of the table.


ΓòÉΓòÉΓòÉ 48.3. Examples ΓòÉΓòÉΓòÉ

Loading a table from dBase:

OPEN DATASESSION sess, CONNECT="DRV=QEDBF", AUTOCOMMIT=1
OPEN TABLE       tab,  sess, NAME="..." ...
OPEN DATATRANS   tran, sess, ACCESS="Seq", TABLE=tab
CALL tran'SETEXPR( "SELECT * FROM EmpData" )
CALL tran'SNAPSHOT()
SHUT sess

Reading records from DB/2:

OPEN DATASESSION sess,
 CONNECT="DRV=QEDB2;SRVR=...;UID=TWDUSER;PWD=Obvious",
 AUTOCOMMIT=1
OPEN DATATRANS   tran, sess, ACCESS="Seq"
CALL tran'SETEXPR( "SELECT EmployeeNo, EmployeeName FROM EmpData" )
CALL tran'GETNEXTROW(v)

Keyed access to Oracle:

OPEN DATASESSION sess,
 CONNECT="DRV=QEORA;SRVR=...;UID=TWDUSER;PWD=Obvious",
 AUTOCOMMIT=1
OPEN DATATRANS   tran, sess, ACCESS="Random"
CALL tran'SETEXPR( "SELECT EmployeeNo, EmployeeName FROM EmpData" )
CALL tran'GETROW( v, 42 )

Updating SyBase SQL Server:

OPEN DATASESSION sess,
 CONNECT="DRV=QESS;SRVR=...;UID=TWDUSER;PWD=Trivial",
 AUTOCOMMIT=1
CALL sess'COMMAND(
 "UPDATE Salary=Salary*2 " ||
 "IN EMPDATA " ||
 "WHERE EmployeeNo = 09852" )

Loading data into Oracle:

OPEN DATASESSION sess,
 CONNECT="DRV=QEORA;SRVR=...;UID=TWDUSER;PWD=Obvious",
 AUTOCOMMIT=1

DO r = 1 : rows
  DEFINE insert[0]
  INSERT insert[0] = 'INSERT INTO EmpData ( '
  DO c = 1 : cols
    INSERT insert[0] = ColName[c] || IF(c=cols,')',',')
  END
  INSERT insert[0] = 'VALUES ( '
  DO c = 1 : cols
    INSERT insert[0] = ColVal[c,r] || IF(c=cols,')',',')
  END
  CALL sess'COMMAND( insert[0] )
END

Examples source library:


ΓòÉΓòÉΓòÉ 49. DATE() ΓòÉΓòÉΓòÉ

The DATE() function converts a string or a number to a date value.

ΓöÇΓöÇDATE(ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
          ΓööΓöÇvariableΓöÇΓöÿ   ΓööΓöÇformatΓöÇΓöÿ

Examples

More about DATE

See also: Formatting data, PROFILE, RETYPE(), TIME()


ΓòÉΓòÉΓòÉ 49.1. Examples ΓòÉΓòÉΓòÉ

! All these are stored internally to match "25th December, 1994"
d = DATE( "12/25/94", "MDY" )
d = DATE( "25/12/94", "DMY" )
d = DATE( "25th December 1994", "YMD" )
d = DATE( "25th December 1994", "MDY" )
d = DATE( 25121994, "DMY" )
d = DATE( 251294, "DMY" )

! The date can be converted according to other formats
today = DATE()              ! today's date
today'DATEFORMAT = "YYYY"   ! convert format
ThisYear = STRING(today)    ! convert to string
LastYear = ThisYear - 1     ! convert to number

Examples source library:


ΓòÉΓòÉΓòÉ 49.2. More about DATE ΓòÉΓòÉΓòÉ

o DATE() can be used to override the default short date format used when data
  is converted implicitly.

o Examples of unambiguous data that will take precedence over the specified
  format are:

   Names     January, August, or  XII

   Suffixed numbers 10th

   Four-digit year numbers 1993

   DBCS Date Symbols 2M or 5D


ΓòÉΓòÉΓòÉ 50. DDECLIENT ΓòÉΓòÉΓòÉ

The DDECLIENT operates as a DDE client with a DDE server-enabled application.

Attributes

Actions

Events

Examples

More about DDECLIENT

See also: DDESERVER, STREAM


ΓòÉΓòÉΓòÉ 50.1. Attributes ΓòÉΓòÉΓòÉ

APPLICATION            TOPIC
ITEM                   TIMEOUT
CODE                   TRACE


ΓòÉΓòÉΓòÉ 50.1.1. APPLICATION ΓòÉΓòÉΓòÉ

The server application of interest. Its value may be any character string
recognized as an active DDE server. The string is limited to 255 bytes, and
must not contain / or \ characters.

If the string APPLICATION is not valid, an error condition is raised. If there
is not an active DDE server for the specified APPLICATION or TOPIC, the OPEN
will fail.

Default: None, APPLICATION must be set on OPEN (then read-only).


ΓòÉΓòÉΓòÉ 50.1.2. TOPIC ΓòÉΓòÉΓòÉ

The server topic of interest. Its value may be any character string recognized
as a supported topic by the server. The string is limited to 255 bytes. If
there is not an active DDE server for the specified APPLICATION or TOPIC, the
OPEN will fail.

Default: None, TOPIC must be set on OPEN (then read-only).


ΓòÉΓòÉΓòÉ 50.1.3. ITEM ΓòÉΓòÉΓòÉ

The name of a server item. It is queried on receipt of a DATA event to identify
the item of interest that has been changed. See the ADVISE action and the DATA
event descriptions for more details.


ΓòÉΓòÉΓòÉ 50.1.4. TIMEOUT ΓòÉΓòÉΓòÉ

The timeout period (in seconds), beyond which the DDECLIENT object will
consider that a DDE server has ceased to be responsive. The value should a
nonnegative number (a value of zero indicates an indefinite timeout period).

The value of TIMEOUT represents a minimum overall timeout since some operations
involve multiple communications between DDE partners. The timeout period will
apply to each communication.

If Ctrl+Break is used to interrupt an application while it is waiting for a DDE
response, the DDECLIENT object will behave as if the TIMEOUT period had
expired.

Default: 0, set on OPEN (then read-write).


ΓòÉΓòÉΓòÉ 50.1.5. CODE ΓòÉΓòÉΓòÉ

This attribute may be queried to obtain the error code of the last DDECLIENT
operation.

Code is set only when the error was a DDE error. Validation errors on attribute
modification, or calling actions, do not set CODE.


ΓòÉΓòÉΓòÉ 50.1.6. TRACE ΓòÉΓòÉΓòÉ

Whether a trace file, called FTBDDE, is produced for diagnostic purposes:

0         Tracing off
Nonzero   Tracing on

Default: 0 (Off)


ΓòÉΓòÉΓòÉ 50.2. Actions ΓòÉΓòÉΓòÉ

SYSTEM()                  QUERYFORMATS()
VERIFYFORMAT()            REQUEST()
ADVISE()                  UNADVISE()
DELIVER()                 EXECUTE()


ΓòÉΓòÉΓòÉ 50.2.1. SYSTEM() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSYSTEM(Variable,Item)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action is used to obtain information about the capabilities of the server.
It relies on the server having populated the SYSTEM topic with information on
the requested item.

Note:   If no information exists for the item, Variable will be defined with
        zero elements (if undeclared) or populated with nulls (if a scalar or
        declared vector).

If no response is received from the server within the TIMEOUT period, an error
condition is raised.

Item is provided by the caller, and must be a character string limited to 255
bytes. Variable is the name of a vector or scalar to be populated with
information about the item. If it is a declared vector, the dimensions of the
vector are fixed, and any excess information will be truncated. If it is an
undeclared vector, it will expand as required to hold all the information on
the item.


ΓòÉΓòÉΓòÉ 50.2.2. QUERYFORMATS() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇQUERYFORMATS(Formats)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action may be used to obtain information about the format capabilities of
the server. It relies on the server having populated the FORMATS item of the
SYSTEM topic. If no format information has been provided by the server, no
information is returned, this is not treated as an error.

If no response is received from the server within the TIMEOUT period, an error
condition is raised.

Formats is the name of a vector or scalar to be populated with server format
information. If it is a declared vector, the dimensions of the vector are
fixed, and any excess information will be truncated. If it is an undeclared
vector, it will expand as required to hold all the format information.


ΓòÉΓòÉΓòÉ 50.2.3. VERIFYFORMAT() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇVERIFYFORMAT(Format)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action may be used as an alternative to QUERYFORMATS to verify that the
server can render a specific format. It will return 1 if the format is
available, or 0 if not.

Formats will be the name of the format of interest.

If no response is received from the server within the TIMEOUT period, an error
condition is raised.


ΓòÉΓòÉΓòÉ 50.2.4. REQUEST() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇREQUEST(Item,Format)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action may be used to obtain data from the server on the item specified,
in the format specified. This format may be known to be supported by the
server, or may have been arrived at by looking at the server information in the
SYSTEM topic.

The REQUEST action will result in an ON TARGET event by which the data is
delivered to the client in the format specified.

If the specified item/format combination is not supported by the server, an
error condition is raised.

If no response is received from the server within the TIMEOUT period, an error
condition is raised.


ΓòÉΓòÉΓòÉ 50.2.5. ADVISE() ΓòÉΓòÉΓòÉ

                        ΓöîΓöÇ0ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöÇΓöÇADVISE(Item,Format,ΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                        ΓööΓöÇImmediateΓöÇΓöÿ

This action may be used to register an interest in a specified item, such that
the client is notified whenever the item is updated. The registration is
qualified by Format so that a client can potentially receive multiple
notifications when a single item changes. Multiple ADVISEs for the same
item/format combination are treated as a single ADVISE.

If the specified item is not supported by the server, an error condition is
raised. If the specified format is not supported by the server, an error
condition is raised. If no format is specified, or no format match can be made,
an error condition is raised. If no response is received from the server within
the TIMEOUT period, an error condition is raised.

By default, the client will receive one DATA event whenever the item changes
(regardless of the number of ADVISES for the item in different formats), at
which point the client might issue a REQUEST action. However, if the optional
Boolean Immediate parameter is specified as 1, the client will receive a TARGET
event whenever the item changes.


ΓòÉΓòÉΓòÉ 50.2.6. UNADVISE() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇUNADVISE(ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
              ΓööΓöÇItemΓöÇΓöÿ   ΓööΓöÇFormatΓöÇΓöÿ

This action removes a registration of interest for a prior ADVISE. If no
matching advise has been issued, the UNADVISE is ignored. If Format is not
specified, all ADVISEs for the Item are cancelled. If Item is not specified,
all ADVISEs are cancelled.

If no response is received from the server within the TIMEOUT period, an error
condition is raised.


ΓòÉΓòÉΓòÉ 50.2.7. DELIVER() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇDELIVER(Item,Format)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action allows the client to send data to the server in a format of the
clients choice. This action will generate a SOURCE event at the client as
described below.

Item identifies the item to be delivered, and is reflected in the OBJECTNAME
attribute of the STREAM object passed with the SOURCE event.

Format identifies the data format and is reflected in the OBJECTNAME attribute
of the STREAM object passed with the SOURCE event.

If no response is received from the server within the TIMEOUT period, an error
condition will be raised.


ΓòÉΓòÉΓòÉ 50.2.8. EXECUTE() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇEXECUTE(Variable)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action allows the client to send a command string to the server. variable
may be a scalar or vector. By convention, the command string will be used by
the server according to an agreed protocol. If variable is a multi-element
vector, the element values are concatenated for delivery to the server.

When setting a value for TIMEOUT, consideration should be given to the amount
of time a server might need to process a command sent from EXECUTE.

If no response is received from the server within the TIMEOUT period, an error
condition will be raised.

If the server cannot process the command, an error condition will be raised.

If the server accepts the command, but encounters an error in processing it,
EXECUTE may return a numeric value qualifying the error. If the server is an
instance of DDESERVER, the return value is taken from the value of the STATUS
attribute of the STREAM, as set by the server in its ON TARGET block.

The time taken by a server to process a command sent with EXECUTE is impossible
to predict in the general case. However, a client may know how a specific
server will behave, and may deem that a TIMEOUT value specific to EXECUTE is
needed. This can be achieved by modifying the TIMEOUT attribute value before
and after issuing the EXECUTE.


ΓòÉΓòÉΓòÉ 50.3. Events ΓòÉΓòÉΓòÉ

DATA                       SOURCE(pStream)
TARGET(pStream)            QUIT
ERROR


ΓòÉΓòÉΓòÉ 50.3.1. DATA ΓòÉΓòÉΓòÉ

This event occurs when the DDECLIENT has issued an ADVISE without the
"Immediate" parameter, and the specified item has been modified.
A.System.Object identifies the DDECLIENT object that generated the event. The
program typically issues a REQUEST action against the DDECLIENT object to
request that the modified data be delivered to it.

Query the DDECLIENT'ITEM attribute to get the name of the changed item.


ΓòÉΓòÉΓòÉ 50.3.2. SOURCE(pStream) ΓòÉΓòÉΓòÉ

This event occurs when the DELIVER action is invoked. pStream is a pointer to a
STREAM object delivered with the event, through which the data may be rendered.
The OBJECTNAME attribute of the STREAM object will return the value passed as
the Item parameter to the DELIVER action.

After the STREAM has been supplied with data, Call the STREAM'FINISHED() action
to trigger delivery of the data to the server. If an error occurs while loading
data into the stream, set the STREAM'STATUS attribute to a nonzero integer
prior to calling the FINISHED() action to cancel the data delivery. The STREAM
should be SHUT immediately after calling the FINISHED() action.


ΓòÉΓòÉΓòÉ 50.3.3. TARGET(pStream) ΓòÉΓòÉΓòÉ

This event occurs when data arrives from a DDE server, either in response to a
REQUEST action, or an ADVISE action with the "Immediate" parameter specified.
pStream is a pointer to a STREAM object delivered with the event, from which
the supplied data may be extracted. At the end of TARGET event processing, call
the STREAM'FINISHED() action. If errors were encountered extracting the data,
the STATUS attribute of the STREAM should be set to a nonzero number prior to
calling FINISHED(). The STREAM should be SHUT immediately after calling
FINISHED().


ΓòÉΓòÉΓòÉ 50.3.4. QUIT ΓòÉΓòÉΓòÉ

This event occurs when the server terminates, or no longer services the TOPIC

A.System.Object identifies the DDECLIENT object.


ΓòÉΓòÉΓòÉ 50.3.5. ERROR ΓòÉΓòÉΓòÉ

Error in processing data. A.System.Object identifies the DDECLIENT object.


ΓòÉΓòÉΓòÉ 50.4. Examples ΓòÉΓòÉΓòÉ

See the DDEC.PRG and DDES.PRG samples supplied in the Development Samples
folder.

Examples source library:


ΓòÉΓòÉΓòÉ 50.5. More about DDECLIENT ΓòÉΓòÉΓòÉ

o Both APPLICATION and TOPIC should be set on open.  If a matching active DDE
  server is not found, an error condition will occur.


ΓòÉΓòÉΓòÉ 51. DDESERVER ΓòÉΓòÉΓòÉ

The DDESERVER operates as a DDE server with a DDE client-enabled application.

Attributes

Actions

Events

Examples

More about DDESERVER

See also: DDECLIENT, STREAM

Also refer to the OS/2 Programming Guide - Volume II


ΓòÉΓòÉΓòÉ 51.1. Attributes ΓòÉΓòÉΓòÉ

APPLICATION            TOPIC
MAXCLIENTS             CLIENTS
CODE                   TRACE


ΓòÉΓòÉΓòÉ 51.1.1. APPLICATION ΓòÉΓòÉΓòÉ

This attribute must be set at OPEN time, and subsequently queried. It
identifies the server application name. Its value may be any character string
up to 255 bytes long, and must not contain forward slash (/) or backward slash
(\) characters.

If an invalid string is assigned to APPLICATION, an error condition is raised.


ΓòÉΓòÉΓòÉ 51.1.2. TOPIC ΓòÉΓòÉΓòÉ

This attribute must be set at OPEN time, and subsequently queried. It
identifies the current server topic. Its value may be any character string up
to 255 bytes long.

"SYSTEM" is a reserved TOPIC name. If TOPIC is set to this value an error
condition will result.


ΓòÉΓòÉΓòÉ 51.1.3. MAXCLIENTS ΓòÉΓòÉΓòÉ

This attribute may be set at OPEN time, and subsequently queried. It may be
used to limit the number of concurrent clients that the DDESERVER object will
connect to. The default value is 0, indicating no limit. Any value specified
must be a positive integer.


ΓòÉΓòÉΓòÉ 51.1.4. CLIENTS ΓòÉΓòÉΓòÉ

This attribute may be queried to obtain the number of DDE clients currently in
conversation with this DDESERVER.


ΓòÉΓòÉΓòÉ 51.1.5. CODE ΓòÉΓòÉΓòÉ

This attribute may be queried to obtain the error code of the last DDESERVER
operation.

Code is set only when the error was a DDE error. Validation errors on attribute
modification, or calling actions, do not set CODE.


ΓòÉΓòÉΓòÉ 51.1.6. TRACE ΓòÉΓòÉΓòÉ

Whether a trace file, called FTBDDE, is produced for diagnostic purposes:

0         Tracing off
Nonzero   Tracing on

Default: 0 (Off)


ΓòÉΓòÉΓòÉ 51.2. Actions ΓòÉΓòÉΓòÉ

SYSTEM()                  FORMATS()
INFORM()                  QUERYADVISES()
ADVISE()


ΓòÉΓòÉΓòÉ 51.2.1. SYSTEM() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSYSTEM(Variable,Item)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action may be used to supply information about the capabilities of the
server. Some products may rely on this information being available when acting
as a client.

Item is provided by the caller, and must be a character string limited to 255
bytes. Variable is the name of a scalar or vector, or a literal, containing
information about the item. The scalar or vector may be declared data or
undeclared data.

The contents of Variable will replace any existing information on the specified
item.

The SYSITEMS item will be updated automatically by DDESERVER whenever the
SYSTEM action is used. For this reason, "SYSITEMS" is a reserved value that may
not be specified as the first parameter to the SYSTEM action.


ΓòÉΓòÉΓòÉ 51.2.2. FORMATS() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇFORMATS(Formats)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action may be used to supply information about the format capabilities of
the server.

Formats is the name of a scalar or vector, or a literal, containing the
format(s) supported by the server. The scalar or vector may be declared data or
undeclared data.

The contents of Formats will replace any existing information on for the
FORMATS item within the SYSTEM topic.


ΓòÉΓòÉΓòÉ 51.2.3. INFORM() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇINFORM(Item)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action will inform all clients with a current ADVISE on Item that the item
has been updated.


ΓòÉΓòÉΓòÉ 51.2.4. QUERYADVISES() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇQUERYADVISES(Items,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                        ΓööΓöÇFormatsΓöÇΓöÿ

This action allows the server to discover what ADVISEs are currently active.

Items is the name of a vector or scalar, declared or undeclared, to be
populated with items for which there are active advises. If it is a scalar or
declared vector, its dimensions are fixed, and any excess item information will
be truncated. If it is an undeclared vector, it will expand as required to hold
all the item information.

Formats may optionally be set to the name of a vector or scalar, declared or
undeclared, to be populated with format information for active advises. If it
is a scalar or declared vector, its dimensions are fixed, and any excess format
information will be truncated. If it is an undeclared vector, it will expand as
required to hold all the format information.

If Formats is provided, Items and Formats will be populated with information
for each unique item/format combination. If Formats is omitted, Items will be
populated with one entry for each unique item.


ΓòÉΓòÉΓòÉ 51.2.5. ADVISE() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇADVISE(ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
            ΓööΓöÇItemΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÿ
                   ΓööΓöÇ,FormatΓöÇΓöÿ

This action allows the server to discover how many advises are currently active
for a given item and format. item is optional. When present, it is the name of
an item supported by the server. Format is also optional and is the name of a
data format supported by the server. If both item and Format are provided,
ADVISE() returns the number of client ADVISE actions for the item and format
combination.

If the specified item and format combination is not supported by the server, an
error condition is raised. If no item or no format is specified, ADVISE() will
return the total number of client ADVISE() actions without regard to item or
format.


ΓòÉΓòÉΓòÉ 51.3. Events ΓòÉΓòÉΓòÉ

ADVISE(pStream)                INITIATE(pDDEserver)
SOURCE(pStream)                TARGET(pStream)
ERROR


ΓòÉΓòÉΓòÉ 51.3.1. ADVISE(pStream) ΓòÉΓòÉΓòÉ

This event occurs when a client issues an ADVISE without specifying that an
immediate delivery of data is required. pStream points to a STREAM object
delivered with the event.

The OBJECTNAME and FORMAT attributes of the STREAM identify the item that the
advise is for, and the format of interest.

If the program is capable of rendering the item in the requested format, it
should call the FINISHED action of the STREAM and then SHUT the STREAM.

If the program is not capable of rendering the data, it should set the STATUS
attribute of the STREAM to a number greater than 0 prior to calling FINISHED
and shutting the STREAM. This will signal to the client that the ADVISE is not
accepted.


ΓòÉΓòÉΓòÉ 51.3.2. INITIATE(pDDEserver) ΓòÉΓòÉΓòÉ

This event occurs when a DDE client initiates a new conversation with the
DDESERVER object. If this information is not of interest to the ASL program,
then the event does not need to be coded.

pDDEserver is a pointer to the DDESERVER object that raised the event.


ΓòÉΓòÉΓòÉ 51.3.3. SOURCE(pStream) ΓòÉΓòÉΓòÉ

This event occurs when a client requests data. It also occurs immediately in
response to an INFORM action when there is at least one client with an
immediate ADVISE in effect.

pStream points to a STREAM object delivered with the event, through which the
supplied data may be rendered. The OBJECTNAME attribute of the STREAM object
identifies the required item. The FORMAT attribute identifies the format in
which the data is required.

At the end of ON SOURCE processing, the FINISHED() action of the STREAM should
be called. This will trigger delivery of the data to the client(s).

If an error occurs populating the STREAM, then the STATUS attribute of the
STREAM should be set to a nonzero integer prior to the FINISHED() action. The
STREAM should be SHUT immediately after calling the FINISHED() action.


ΓòÉΓòÉΓòÉ 51.3.4. TARGET(pStream) ΓòÉΓòÉΓòÉ

This event occurs when a client delivers data to the server using a DDE Poke
(the DELIVER action on DDECLIENT), or when it sends a DDE Execute to the server
(the EXECUTE action on DDECLIENT).

pStream points to a STREAM delivered with the event, from which the supplied
data may be extracted. If the TARGET event was generated as a result of an
EXECUTE action at the client, then the FORMAT attribute is "FTBCOMMAND".

At the end of ON TARGET processing, the FINISHED() action of the STREAM should
be called.

If an error occurs processing the STREAM data, the STATUS attribute of the
STREAM should be set to a nonzero integer prior to the FINISHED() action. The
STREAM should be SHUT immediately after calling the FINISHED() action.


ΓòÉΓòÉΓòÉ 51.3.5. ERROR ΓòÉΓòÉΓòÉ

Error in processing data.


ΓòÉΓòÉΓòÉ 51.4. Examples ΓòÉΓòÉΓòÉ

See the DDEC.PRG and DDES.PRG samples supplied in the Development Samples
folder.

Examples source library:


ΓòÉΓòÉΓòÉ 51.5. More about DDESERVER ΓòÉΓòÉΓòÉ

o The SYSTEM topic is a DDE convention that relies on the cooperation of DDE
  servers to provide some standard items of information. This information may
  be of general interest to DDE clients.

  Because of the special convention associated with the SYSTEM topic, the
  DDESERVER and DDECLIENT objects give access to item information within the
  SYSTEM topic by using the SYSTEM action. However, the SYSTEM topic is
  actually no different to any other topic, and information can be exchanged
  between client and server in the same way as any other topic.


ΓòÉΓòÉΓòÉ 52. DECLARE ΓòÉΓòÉΓòÉ

DECLARE can be used to declare local data, global data, and the existence of
objects.

Use DECLARE for efficient use of parameters, local data, or TASK data. Also,
use DECLARE to retain values between procedure calls, or when recursive calls
may occur.

                                    ΓöîΓöÇ[1]ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöÇΓöÇDECLAREΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇdatatypeΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇnameΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
             ΓööΓöÇoptionsΓöÇΓöÿ            ΓööΓöÇ[limit]ΓöÇΓöÿ        ΓööΓöÇ[extent]ΓöÇΓöÿ
ΓöÇΓöÇ=ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
     ΓööΓöÇinitializerΓöÇΓöÿ

Examples

More about DECLARE

See also: OPEN


ΓòÉΓòÉΓòÉ 52.1. Examples ΓòÉΓòÉΓòÉ

/*---------------------------------*/
/* Variable initialization routine */
/*---------------------------------*/
PROCEDURE INIT( size )
DO
  DECLARE NUMERIC size
  DECLARE TASK NUMERIC already = 0
  DECLARE NUMERIC i
  IF \already
  THEN DO
    already = 1
    DO i=1 : size
      ...
    END
  END
END

DECLARE NUMERIC first = 1
ON SELECT
DO
  IF first
  THEN CALL INIT()
  ...
END
ON DATA
DO
  IF first
  THEN CALL INIT()
  ...
END

/*-------------------*/
/* Factorial routine */
/*-------------------*/
PROCEDURE FACTORIAL( x )
DO
  DECLARE NUMERIC x
  DECLARE NUMERIC xfac
  IF x > 0
  THEN xfac = x * FACTORIAL(x-1)
  ELSE xfac = 1
  RETURN xfac
END

Examples source library:


ΓòÉΓòÉΓòÉ 52.2. More about DECLARE ΓòÉΓòÉΓòÉ

o Purpose of DECLARE

  Use DECLARE as follows:

   - Declare parameters for efficiency.

   - Declare task data for values to be retained between procedure calls.

   - Declare local or task data for efficiency.

   - Declare local data if recursive calls will occur.

o Scope of the variables

  The attributes LOCAL, TASK, and GLOBAL describe the scope of the data.

  GLOBAL data is data known outside the task (A.. or M.. for example) and is
  DECLAREable only for consistency. GLOBAL data may not specify limits,
  extents, or initializers. Variables which are not DECLAREd are GLOBAL by
  default.

  TASK data is allocated when the task starts, and remains allocated until the
  task stops. Values held by TASK data are persistent.

  LOCAL data is allocated on entry to a block, and remains allocated until the
  ON or PROCEDURE block returns. Values held by LOCAL data are lost when a
  block returns.

o Position of DECLARE

  The position of a DECLARE statement defines the scope of the name.

  DECLARE statements may occur outside of any block. In this case, LOCAL has no
  meaning and the default is TASK. The name may be used anywhere in the task.

  DECLARE statements may occur as the first statements of any ON or PROCEDURE
  block. The default is LOCAL, but TASK may be specified. The name is only
  known within the block. The same name may be used in other blocks or outside
  of all blocks without conflict.

  A TASK variable declared inside a block is allocated as for all TASK
  variables, but the name is only known within the block.

  The parameters to a block may be declared. These declarations must appear
  before all other declarations in the block. Parameters may not specify array
  extents or initializers.

o Initial values and clear

  Initializers apply to all values in an array.

  If there is no initializer for a LOCAL variable, it is not initialized, and
  use of the variable will have unpredictable results.

  The CLEAR statement or the CLEAR option can be used to set a variable to an
  initial state. TASK variables with no initializer are set to this clear
  state. If the variable will accept NULLS, the initial state is NULL,
  otherwise it depends on the data type.

o Variable extents and initializers

  The limit, extent, and initializer for a particular variable may be constant
  or variable.

  For LOCAL data, any variables used must be known prior to the declaration.
  This includes global data, task data, and data local to the same block
  (including parameters), but the data must be declared earlier in the program.

  For TASK data, any variables used must be known prior to the declaration.
  This includes global data and task data, but the data must be declared
  earlier in the program.

  TASK data with no variables involved is allocated and initialized by the
  compiler; all other data is allocated and initialized by executable code.

o Dynamic allocation

  Storage for TASK data which is declared with the DEFINED attribute is
  allocated dynamically by the DEFINE statement. It may be defined to any size
  and to 1 or 2 dimensions. If it has already been defined, any data which it
  contains is lost. Storage may be released by defining it back to [0].

o Indirection

  Declared data does not have a name at execution time, so the syntax
  POINTER("var") cannot work. Instead, the syntax POINTER(var[0]) must be used.
  This syntax is valid for GLOBAL data as well.

o Data attributes

  Certain data attributes are supported for declared data. All other attributes
  are tolerated for query, and deliver zero or an empty string, as appropriate.
  Only the format attributes may be modified.

  At the element level, TYPE, FORMAT, DATEFORMAT, and TIMEFORMAT attributes are
  supported. At the dictionary level, ENTRIES, WIDTH, DIMENSIONS, and MULTS are
  supported in addition to the element level format attributes.

o Object handlers

  Object handlers which accept vector input by name, such as
  REFERENCE="myvector", will accept the syntax REFERENCE=myvector[0] for both
  declared and global data.

o Restrictions of DECLARE

  The following are restrictions of DECLARE:

   RENAME    cannot be used on declared data.

   DELETE    cannot be used on declared data.

   CLEAR     Sets all elements to NULL if acceptable, otherwise an initial
             value

   COPY      If COPY copies to declared data, the receiver must be the correct
             shape, and must be sufficiently large, otherwise data will be
             lost. Extra elements in the receiver are cleared.

   INSERT    is not supported.

   { }       is not supported.

   Objects   Declared data cannot be used as an object handle.

   ASL-C     Declared data values can be used across this interface, but
             declared data cannot be accessed by a handle.

   INDEX     is not supported

   NAMES     is not supported for DECLAREd data and only generates GLOBAL data
             output

   GATHER/ANALYZE Only generate GLOBAL data output

   FILE'GET( ) Only generates GLOBAL data output

   ENTRIES( ) Not supported for DECLAREd data, use [0]'ENTRIES instead

o Vector output

  Many operations generate output vectors. Examples are:

   - COPY
   - SYSTEM'FILE( ) and SYSTEM'FILES( )
   - CLIPBOARD'GET( )
   - GATHER and ANALYSE.

  Not all such operations can generate declared data vectors. In the cases in
  which it can be done, these are the rules:

   - If the target has the DEFINED attribute, it will be allocated with a
     suitable number of elements. If it already holds data, that data will be
     lost.

   - If the target does not have the DEFINED attribute, it will be filled with
     data. If it is smaller than required, data will be lost, and if it is
     larger, the data will be padded with CLEAR values.


ΓòÉΓòÉΓòÉ 53. DEFINE statement ΓòÉΓòÉΓòÉ

The DEFINE statement has three uses:

o To allocate an array and specify the number of elements in the array
o To declare the columns of a table after it is created using OPEN TABLE
o To resize arrays which have already been defined.

ΓöÇΓöÇDEFINEΓöÇΓöÇvariablerefΓöÇΓöÇΓö¼ΓöÇ[ΓöÇΓöÇexp1ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇ]ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                         Γöé          ΓööΓöÇ,exp2ΓöÇΓöÿ     ΓööΓöÇ=exp3ΓöÇΓöÿ Γöé
                         ΓööΓöÇ[ΓöÇΓöÇexp1=*ΓöÇΓöÇ]ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

Examples

More about DEFINE

See also: CLEAR, DECLARE, DELETE, INSERT, GRAPHIC, ENTRIES()

Also see Dictionary attributes for the following attributes:

DIMENSIONS
ENTRIES
MULTS


ΓòÉΓòÉΓòÉ 53.1. Examples ΓòÉΓòÉΓòÉ

To define a vector and insert three elements into it:

DEFINE vec[0]
INSERT vec[0] = "First entry"
INSERT vec[0] = "Second entry"
INSERT vec[0] = "Third entry"

DECLARE TASK DEFINED CHARACTER[*] dvec
DEFINE dvec[3]
dvec[1] = "First entry"
dvec[2] = "Second entry"
dvec[3] = "Third entry"

More examples of DEFINE:

DEFINE Array[ size ]
DEFINE Matrix[ rows, cols ]

DEFINE Employee.Name[*]

DEFINE Status[100] = "Empty"

If you have already used a scalar variable with the same name that you now wish
to use as a vector, then you must delete the original variable:

x = 666       ! x already exists as a scalar
DELETE x
DEFINE x[0]   ! x is now a vector.

Examples source library:


ΓòÉΓòÉΓòÉ 53.2. More about DEFINE ΓòÉΓòÉΓòÉ

o For global data where the array already exists, values that survive resizing
  are not changed. If DEFINE specifies more elements than already exist, then
  the array is expanded accordingly (if exp3 is given, then only the extra
  elements are set to that value). If fewer elements are specified, then the
  surplus elements are deleted and exp3 is ignored.

o For declared data, the array must be declared TASK DEFINED. If the array
  already exists, its contents are discarded.

o The first element in arrays that can be accessed by number is element 1.
  Values in two-dimensional arrays are ordered by row.

o Attributes of element 0 of any array or table refer to the whole array or
  column.

o If a reference is made to an element that lies outside the defined bounds, a
  NULL value is returned. If an assignment is made to such an element, an error
  occurs.

o Arrays can be defined with exp1 or exp2 set to value zero. In this case, the
  array has no elements until it is resized.


ΓòÉΓòÉΓòÉ 54. DEFINE object ΓòÉΓòÉΓòÉ

The DEFINE object class creates a graphics object that can be treated as if it
were a graphics primitive. Several graphic primitives can be opened to a single
DEFINE and the DEFINE can then be manipulated (rotated, dragged, or scaled) as
if it were a single graphic primitive.

Parent: GRAPHIC

Attributes

Actions: None.

Events

More about DEFINE

See also: GRAPHIC, Standard graphics attributes


ΓòÉΓòÉΓòÉ 54.1. Attributes ΓòÉΓòÉΓòÉ

CLIPMINX              CLIPMINY
CLIPMAXX              CLIPMAXY
DRAGABLE              DRAGBORDER
MOVEX                 MOVEY
ORIGINX               ORIGINY
ROTATE                ROTATEX
ROTATEY               SCALEX
SCALEY

The following standard graphics attributes are also available. See
Standard graphics attributes:

COLOR                  FILLPATTERN
LINEWIDTH              SELECTED
FILLCOLOR              LINESTYLE
SELECTABLE             VISIBLE


ΓòÉΓòÉΓòÉ 54.1.1. CLIPMINX ΓòÉΓòÉΓòÉ

X coordinate at bottom left corner of clip window through the DEFINE.

Default: -32000


ΓòÉΓòÉΓòÉ 54.1.2. CLIPMINY ΓòÉΓòÉΓòÉ

Y coordinate at bottom left corner of clip window through the DEFINE.

Default: -32000


ΓòÉΓòÉΓòÉ 54.1.3. CLIPMAXX ΓòÉΓòÉΓòÉ

X coordinate at top right corner of clip window through the DEFINE.

Default: 32000


ΓòÉΓòÉΓòÉ 54.1.4. CLIPMAXY ΓòÉΓòÉΓòÉ

Y coordinate at top right corner of clip window through the DEFINE.

Default: 32000


ΓòÉΓòÉΓòÉ 54.1.5. DRAGABLE ΓòÉΓòÉΓòÉ

Whether the object can be dragged:

0         Object cannot be dragged
1         If selectable, the object can be dragged.

Default: 0 (Cannot be dragged)


ΓòÉΓòÉΓòÉ 54.1.6. DRAGBORDER ΓòÉΓòÉΓòÉ

Whether the object has a border drawn around it when it is being dragged:

0         No border
1         Border

Default: 0 (No border)


ΓòÉΓòÉΓòÉ 54.1.7. MOVEX ΓòÉΓòÉΓòÉ

X coordinate of the position to which the define object has moved after
dragging.

Default: 0


ΓòÉΓòÉΓòÉ 54.1.8. MOVEY ΓòÉΓòÉΓòÉ

Y coordinate of the position to which the define object has moved after
dragging.

Default: 0


ΓòÉΓòÉΓòÉ 54.1.9. ORIGINX ΓòÉΓòÉΓòÉ

X origin from which scaling is calculated.

Default: 0


ΓòÉΓòÉΓòÉ 54.1.10. ORIGINY ΓòÉΓòÉΓòÉ

Y origin from which scaling is calculated.

Default: 0


ΓòÉΓòÉΓòÉ 54.1.11. ROTATE ΓòÉΓòÉΓòÉ

Angle to which the DEFINE is to be rotated around the point defined by
attributes ROTATEX and ROTATEY.

Default: 0


ΓòÉΓòÉΓòÉ 54.1.12. ROTATEX ΓòÉΓòÉΓòÉ

X coordinate of the position around which the ROTATE is to be carried out.

Default: 0


ΓòÉΓòÉΓòÉ 54.1.13. ROTATEY ΓòÉΓòÉΓòÉ

Y coordinate of the position around which the ROTATE is to be carried out.

Default: 0


ΓòÉΓòÉΓòÉ 54.1.14. SCALEX ΓòÉΓòÉΓòÉ

The X scale of the current object as a percentage.

Default: 100


ΓòÉΓòÉΓòÉ 54.1.15. SCALEY ΓòÉΓòÉΓòÉ

The Y scale of the current object as a percentage.

Default: 100


ΓòÉΓòÉΓòÉ 54.2. Events ΓòÉΓòÉΓòÉ

DRAG              OPEN
SELECT


ΓòÉΓòÉΓòÉ 54.2.1. DRAG ΓòÉΓòÉΓòÉ

Dragging is finished.


ΓòÉΓòÉΓòÉ 54.2.2. OPEN ΓòÉΓòÉΓòÉ

Mouse button 1 is clicked twice.


ΓòÉΓòÉΓòÉ 54.2.3. SELECT ΓòÉΓòÉΓòÉ

Signaled when selection is made. A.System.Object is set to named graphic area
and A.System.PositionX and A.System.PositionY are set to the coordinates of the
point selected.  Coordinates are in world coordinate scale units.


ΓòÉΓòÉΓòÉ 54.3. More about DEFINE ΓòÉΓòÉΓòÉ

o When manipulating individual graphic primitives on a define, the PARENT
  attribute of each graphic object will return the name of the define that owns
  the object.


ΓòÉΓòÉΓòÉ 55. DEFINED() ΓòÉΓòÉΓòÉ

The DEFINED() function tests whether the value of an expression is non-NULL. If
so, it returns 1 (true).

ΓöÇΓöÇDEFINED(expression)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Examples

See also: NULL()


ΓòÉΓòÉΓòÉ 55.1. Examples ΓòÉΓòÉΓòÉ

DECLARE TASK NULL CLEAR CHARACTER[0] null
x = DEFINED(null)        ! Result is 0

CLEAR val
x = DEFINED(val)         ! Result is 0

val = ""
x = DEFINED(val)         ! Result is 1, "" is not equal to NULL

val = 0
x = DEFINED(val)         ! Result is 1, 0 is not equal to NULL

@ASSERT DEFINED(@month)  ! Ensures @month is set at compile time

Examples source library:


ΓòÉΓòÉΓòÉ 56. DEGREES() ΓòÉΓòÉΓòÉ

The DEGREES() function converts a value specified in radians to degrees.

ΓöÇΓöÇDEGREES(radians)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Examples

See also: RADIANS()


ΓòÉΓòÉΓòÉ 56.1. Examples ΓòÉΓòÉΓòÉ

PRECISION 15
x = DEGREES(1)                  ! Result is 57.2957795130823
x = DEGREES(3.14159265358979)   ! Result is 180

Examples source library:


ΓòÉΓòÉΓòÉ 57. DELETE ΓòÉΓòÉΓòÉ

The DELETE statement is used to remove a variable, an array element, or a table
row.  When deleting a variable, DELETE also removes all the dictionary
attributes of the variable, so that no trace of it remains.

ΓöÇΓöÇDELETEΓöÇΓöÇvariablerefΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                         Γöé <ΓöÇ,ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ Γöé
                         Γö£ΓöÇΓöÇΓöÇ{ΓöÇΓöÇexpression1ΓöÇΓöÇ}ΓöÇΓö┤ΓöÇΓöñ
                         ΓööΓöÇ[ΓöÇΓöÇexpression2ΓöÇΓöÇ]ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

Examples

More about DELETE


ΓòÉΓòÉΓòÉ 57.1. Examples ΓòÉΓòÉΓòÉ

DELETE EmpTab
DELETE Array[6]
DELETE EmpData.Name{ 'Smith' }

Examples source library:


ΓòÉΓòÉΓòÉ 57.2. More about DELETE ΓòÉΓòÉΓòÉ

o When an element is deleted from an array, the number of entries in the array
  is reduced by one, and the relative positions of all entries after the
  deleted element are reduced by one.

o If any element in a table is deleted, then the entire row of which the
  element is a part is deleted.  An element of a table can be deleted by key or
  by element position.

o DELETE cannot be used to delete a whole table. Tables must be deleted column
  by column. The order of deletion of key columns of a table must be minor to
  major.

o You cannot delete from a two-dimensional array.

o You cannot delete declared data.

o If you repeatedly define and then delete a vector, then storage is wasted.
  This can happen in a procedure that is called frequently. To ensure that all
  the space occupied by a vector is reused, either use the CLEAR statement or
  use the DEFINE statement with [0] as the number of elements.


ΓòÉΓòÉΓòÉ 58. DELWORD() ΓòÉΓòÉΓòÉ

The DELWORD() function deletes words from a string and returns the remaining
string.

                                       ΓöîΓöÇ" "ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöÇΓöÇDELWORD(string,start,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ,ΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                          ΓööΓöÇnumberΓöÇΓöÿ   ΓööΓöÇseparatorΓöÇΓöÿ

Examples

More about DELWORD()

See also: ADDWORD()


ΓòÉΓòÉΓòÉ 58.1. Examples ΓòÉΓòÉΓòÉ

s = "The lion is fierce"
x = DELWORD( s, 3 )          ! Result is "The Lion"
x = DELWORD( s, 2, 2 )       ! Result is "The fierce"

s = "His-teeth--can---pierce----"
x = DELWORD( s, 3, , "-" )   ! Result is "His-teeth"
x = DELWORD( s,-1, , "-" )   ! Result is "His-teeth--can"
x = DELWORD( s, 3, 1, "-" )  ! Result is "His-teeth-pierce----"
x = DELWORD( s, 1, 5, "-" )  ! Result is ""

Examples source library:


ΓòÉΓòÉΓòÉ 58.2. More about DELWORD() ΓòÉΓòÉΓòÉ

o A zero-length string is returned if no words are found in string, or if start
  is 1 and number is either unspecified or greater than the number of words in
  the string.

o If a word or words are deleted from the middle of the string (rather than the
  beginning or end), the remaining parts are returned separated only by a
  single separator.

o Automatic conversion of parameters is carried out if necessary.

o If number is negative, it indicates a position relative to the end of the
  string. -1 indicates the last item.

o An error is returned if either start or number is NULL. Real numbers are
  truncated.

o Using a NULL string parameter returns NULL. Using an empty string parameter (
  "") returns an empty string.

o In this function, a word is defined by a combination of separators (the
  default is space), string start, and string end. No lexical, syntactic, or
  semantic analysis is implied.

o If separator is omitted in a DBCS environment, an SBCS space is inserted by
  default, although DBCS spaces are assumed to be the separators used in
  string.

o DBCS characters cannot be used as separators.


ΓòÉΓòÉΓòÉ 59. DIALOG() ΓòÉΓòÉΓòÉ

The DIALOG() function displays a message on the screen. The text of the message
is displayed in a pop-up window together with a visual cue.  Where a choice of
push buttons has been presented to the user, DIALOG() also returns a text
string indicating the end user's response.

ΓöÇΓöÇDIALOG(messageid,0,text)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Examples

More about DIALOG()

See also: ERROR, MESSAGE, WINDOW


ΓòÉΓòÉΓòÉ 59.1. Examples ΓòÉΓòÉΓòÉ

button = DIALOG( "FTB0007", 0, "Error saving file" )

CASE button
  WHEN "ABORT"  ...
  WHEN "RETRY"  ...
  WHEN "IGNORE" ...
END

Examples source library:


ΓòÉΓòÉΓòÉ 59.2. More about DIALOG() ΓòÉΓòÉΓòÉ

o Messages can also be displayed without returning a value representing a push
  button pressed. See MESSAGE for details.

o If the user closes the dialog window by double-clicking on the system icon,
  result will be set to CANCEL.


ΓòÉΓòÉΓòÉ 60. DIVIDE() ΓòÉΓòÉΓòÉ

The DIVIDE() function can be used instead of the division operator. In addition
to performing a division operation, it traps attempts to divide by zero or by
NULL.

ΓöÇΓöÇDIVIDE(expression1,expression2ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                                   ΓööΓöÇ,expression3ΓöÇΓöÿ

Examples

More about DIVIDE()


ΓòÉΓòÉΓòÉ 60.1. Examples ΓòÉΓòÉΓòÉ

x = DIVIDE(Width,Columns,Width)
    ! Divides the width by the number of columns. If the number
    ! of columns is zero or NULL, returns the full width.

Examples source library:


ΓòÉΓòÉΓòÉ 60.2. More about DIVIDE() ΓòÉΓòÉΓòÉ

o The DIVIDE() function can also be used in the Visualizer expression builder
  in Chart, Report, and Query.

o Use the DIVIDE() function only when an attempted division by zero or division
  by NULL is expected. Otherwise, use the division operator.


ΓòÉΓòÉΓòÉ 61. DO...END ΓòÉΓòÉΓòÉ

The DO statement has two uses:

o To mark the start of a set of statements which are to be processed together

o To set up an iteration.

The END statement denotes the end of a block of statements, the start of which
is denoted by a DO statement or a CASE statement.

ΓöÇΓöÇDOΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇstatementsΓöÇΓöÇENDΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
        Γöé                      ΓöîΓöÇ,1ΓöÇΓöÇΓöÇΓöÇΓöÉ  Γöé
        ΓööΓöÇvariable=start:limitΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÿ
                               ΓööΓöÇ,stepΓöÇΓöÿ

Examples

More about DO...END

See also: CASE...WHEN...OTHERWISE...END, ITERATE, LEAVE, TERMINATE, WHILE


ΓòÉΓòÉΓòÉ 61.1. Examples ΓòÉΓòÉΓòÉ

IF ok
DO
  Count += 1
  CALL WRITEDATA(Count)
END

DO i = 1 : 10
  Array[ i ] = -1
END

DO i = 10 : 1 , -0.5
  Array[Count] = i
  Count += 1
END

Examples source library:


ΓòÉΓòÉΓòÉ 61.2. More about DO...END ΓòÉΓòÉΓòÉ

o For every DO statement there must be an END statement.

o A set of statements enclosed by a DO and END is known as a DO block

o Where more than one statement follows a compound statement (such as ON, IF,
  WHILE, or WHEN), the set of statements must be enclosed in a DO block.

o By default, the statements in a DO block are performed once only. Parameters
  can be specified to cause the statements to be performed a number of times,
  within a range of values, and in steps.

o In a repeating DO block where processing is not yet complete, END passes
  control back to the top of the DO block.

o The LEAVE, ITERATE, and TERMINATE statements can be used to control repeating
  DO blocks. See the entries for these statements in this manual.

o In a DO block under the control of a WHILE statement, END passes control back
  to the WHILE statement.

o DO blocks are the logical units which make up the event blocks in a program.
  They also bracket the procedures (the other high level blocks in a program).

o If the END statement occurs at the end of an event block, the program goes
  into a wait state.

o Any NULLs in the controlling variables of a DO...END block cause a data
  conversion error.

o If you alter the value of variable within the scope of the DO block, then the
  iteration of the block is affected.


ΓòÉΓòÉΓòÉ 62. DROPENTRY ΓòÉΓòÉΓòÉ

The DROPENTRY object class creates an instance of a drop-down entry field.

Parent: WINDOW

Attributes

Actions

Events

Examples

More about DROPENTRY

See also: DROPLIST


ΓòÉΓòÉΓòÉ 62.1. Attributes ΓòÉΓòÉΓòÉ

ENABLED               EXPRESSION
HANDLES               HELP
LISTREF               ORIGIN
SIZEX                 SIZEY
TEXTLIMIT             VALUE
VISIBLE               X
Y


ΓòÉΓòÉΓòÉ 62.1.1. ENABLED ΓòÉΓòÉΓòÉ

Whether the drop-down entry field is enabled:

0         Drop-down entry field disabled-list push button grayed out
1         Drop-down entry field enabled

Default: 1 (Enabled)


ΓòÉΓòÉΓòÉ 62.1.2. EXPRESSION ΓòÉΓòÉΓòÉ

This attribute may be set at open time, then modified and queried at any time.

It may be modified to the name of an ASL variable that will reflect the current
value of the DROPENTRY control. If the variable is updated, the value displayed
in the SLE part of DROPENTRY will change in unison. If a new value is typed or
selected in the DROPENTRY, the ASL variable will be updated. Values returned to
the ASL variable will be limited in length to the current TEXTLIMIT attribute
value of DROPENTRY.

Modifying EXPRESSION replaces any prior modification of the VALUE attribute.


ΓòÉΓòÉΓòÉ 62.1.3. HANDLES ΓòÉΓòÉΓòÉ

Whether sizing handles are attached to the drop-down entry field to support
moving, sizing, and copying operations. These direct manipulation techniques
follow the CUA (Common User Access) guidelines. See also the AUTOSELECT
attribute of the WINDOW object.

0         Handles are not displayed
1         Handles are displayed

Default: 0 (No handles)


ΓòÉΓòÉΓòÉ 62.1.4. HELP ΓòÉΓòÉΓòÉ

Resource identifier (res ID) of the full help text for this object.

Default: 0


ΓòÉΓòÉΓòÉ 62.1.5. LISTREF ΓòÉΓòÉΓòÉ

This attribute may be set at open time, then modified and queried at any time.

It may be modified to the name of an ASL variable that will contain the
value(s) to be displayed in the LIST part of the DROPENTRY. If the variable is
updated, the value(s) displayed in the LIST part of DROPENTRY will change in
unison, truncated in length to the current TEXTLIMIT attribute value of
DROPENTRY.

Modifying LISTREF replaces any prior setting of values made by the ITEMS
action.


ΓòÉΓòÉΓòÉ 62.1.6. ORIGIN ΓòÉΓòÉΓòÉ

The corner of the enclosing window to be taken as the origin. The position of
the drop-down entry field is measured from this point.

"TL"      Top left
"TR"      Top right
"BL"      Bottom left
"BR"      Bottom right

Default: "BL" (Bottom left)


ΓòÉΓòÉΓòÉ 62.1.7. SIZEX ΓòÉΓòÉΓòÉ

Width of the entry box, in dialog box units

Default: 0


ΓòÉΓòÉΓòÉ 62.1.8. SIZEY ΓòÉΓòÉΓòÉ

Height of the drop-down entry, in dialog box units

Default: 0


ΓòÉΓòÉΓòÉ 62.1.9. TEXTLIMIT ΓòÉΓòÉΓòÉ

This attribute may be used to restrict the number of characters that may be
entered into the SLE part of the DROPENTRY control. It will also cause values
assigned to the VALUE attribute, or selected from the list, to be truncated.
Keyboard invoked paste from the clipboard will fail with an audible beep if the
result would exceed the TEXTLIMIT. A call to the PASTE() action will generate
an error in the same circumstance.

TEXTLIMIT works in exactly the same way as the equivalent attribute on the SLE
control.

Set at open time

Default value is 255. Values in the range 0 to 255 may be assigned.  A value of
0 will inhibit any data entry.


ΓòÉΓòÉΓòÉ 62.1.10. VALUE ΓòÉΓòÉΓòÉ

When queried, this attribute returns the current value of the DROPENTRY
control. When set, the current value of the DROPENTRY control is set to the
supplied value, and that value appears in the SLE part of the DROPENTRY.

Until VALUE is modified, or the user enters or selects a value, it will return
the default value of a zero length character string when queried. Assignments
to this attribute will be truncated to the current TEXTLIMIT value.

Set on open, then read/write but modifying VALUE removes the link between the
DROPENTRY and any previous variable specified by the EXPRESSION attribute.


ΓòÉΓòÉΓòÉ 62.1.11. VISIBLE ΓòÉΓòÉΓòÉ

Whether the drop-down entry field is displayed:

0         Drop-down entry field not displayed
1         Drop-down entry field displayed

Default: 1 (Displayed)


ΓòÉΓòÉΓòÉ 62.1.12. X ΓòÉΓòÉΓòÉ

Horizontal position of the top left corner of the field, in dialog box units.

Default: 0


ΓòÉΓòÉΓòÉ 62.1.13. Y ΓòÉΓòÉΓòÉ

Vertical position of the bottom left corner of the field in dialog box units.

Default: 0


ΓòÉΓòÉΓòÉ 62.2. Actions ΓòÉΓòÉΓòÉ

EDIT()               ITEMS()
SELAREA()


ΓòÉΓòÉΓòÉ 62.2.1. EDIT() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇEDIT(argument)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Enables the programmer to query whether a clipboard operation is supported and,
if it is, to carry it out.

argument is a clipboard query or a clipboard operation.

The following values for argument are used to check whether particular
clipboard operations can be supported with the drop-down entry field in its
current state:

"Querycut" Cut to clipboard
"Querycopy" Copy to clipboard
"Querypaste" Paste from clipboard
"Queryclear" Clear clipboard.

Where clipboard operations are supported, the following values for argument
direct them to be carried out:

"Cut"     Cut to clipboard
"Copy"    Copy to clipboard
"Paste"   Paste from clipboard
"Clear"   Clear clipboard.


ΓòÉΓòÉΓòÉ 62.2.2. ITEMS() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇITEMS(variable)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action populates the list of values. variable may be a scalar or a vector
containing the values to be used. Each invocation of the ITEMS action replaces
all existing items in the DROPENTRY list.

The ITEMS action does not effect the SLE part of the DROPENTRY control, or the
value returned from the VALUE attribute.

The list may contain values up to a length of 255 bytes. However, if a value
from the list is selected to populate the SLE, and its length is greater than
the current TEXTLIMIT, the value will be truncated prior to insertion in the
SLE. The VALUE attribute of the DROPENTRY will return the truncated value.


ΓòÉΓòÉΓòÉ 62.2.3. SELAREA() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSELAREA(start,length)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action selects all or part of the text string in the SLE part of the
DROPENTRY control. The default value for start is 1, and it must be in the
range 1 through 255. The default value for length is 0, and it must be in the
range 0 through 255. start plus length must be less than or equal to 256.

The current insertion point is placed after the last selected character. If
length is 0, the insertion point is placed before the character position
specified in start.


ΓòÉΓòÉΓòÉ 62.3. Events ΓòÉΓòÉΓòÉ

DATA               DESKTOP


ΓòÉΓòÉΓòÉ 62.3.1. DATA ΓòÉΓòÉΓòÉ

The event occurs whenever data entry is completed. Completion of data entry
occurs immediately when a value is selected from the list using the mouse. When
the SLE value is modified by the keyboard, either by data entry or keyboard
navigation of the list values, completion of data entry is deferred until the
DROPENTRY loses focus, or the Enter key is pressed.


ΓòÉΓòÉΓòÉ 62.3.2. DESKTOP ΓòÉΓòÉΓòÉ

Signaled when the drop-down entry field is moved, sized, or copied.
A.System.Operation is set to "MOVE", "SIZE", or "COPY". A.System.Object
contains the name of the control.


ΓòÉΓòÉΓòÉ 62.4. Examples ΓòÉΓòÉΓòÉ

The mouse users may stripe text in the SLE prior to over typing, or display the
list of values by selecting the push button. When the list is displayed the
mouse user may select a value from the list. Selection occurs only when the
mouse selection button is raised, facilitating swiping of the list. If the
mouse pointer is not over the list when the selection button is raised then the
list is removed without a selection having occurred. Selection does not
generate a SELECT event, but does generate a DATA event.

The keyboard user may over type text in the SLE. They may also select values
from the list by use of the up and down cursor keys. Selection by this method
does not constitute completion of data entry. The list itself may be displayed
or removed using F4 or the Alt+DownArrow key combination. When the list is
displayed, the value displayed in the SLE is highlighted in the list, provided
a match can be found. The list is automatically removed in the event of the
Enter key being pressed, or the removal of keyboard focus.

ON START
DO
  DECLARE CHARACTER[10] vector[15]
  DECLARE NUMERIC x
  DO x = 1 : vector[0]'ENTRIES
    LET vector[x] = STRING('Choice _',x)  ! Set vector of values
  END
  OPEN DROPENTRY drop, win,               ! Open the DROPENTRY
   X = 20, SIZEX = 60,
   Y = 50, SIZEY = 40
  CALL drop'ITEMS( vector )               ! Populate the DROPENTRY
  LET drop'VALUE = vector[3]              ! Set initial value
END

ON DATA
DO
  CASE A.System.Object
    WHEN 'T..drop'                        ! Event from the DROPENTRY
      LET value = drop'VALUE              ! Get new selected value
    ...
  END
END

Examples source library:


ΓòÉΓòÉΓòÉ 62.5. More about DROPENTRY ΓòÉΓòÉΓòÉ

o DROPENTRY cannot be cloned.

o In a DBCS environment, a window containing a DROPENTRY has a keyboard status
  line at the bottom for character conversion. This line is added
  automatically.

o The maximum number of rows which you can display in the list is typically
  about 400.


ΓòÉΓòÉΓòÉ 63. DROPLIST ΓòÉΓòÉΓòÉ

The DROPLIST object class creates an instance of a drop-down list.

Parent: WINDOW

Attributes

Actions

Events

Examples

More about DROPLIST

See also: DROPENTRY


ΓòÉΓòÉΓòÉ 63.1. Attributes ΓòÉΓòÉΓòÉ

ENABLED               EXPRESSION
HANDLES               HELP
LISTREF               ORIGIN
SIZEX                 SIZEY
VALUE                 VISIBLE
X                     Y


ΓòÉΓòÉΓòÉ 63.1.1. ENABLED ΓòÉΓòÉΓòÉ

Whether the drop-down list is enabled:

0         Drop-down list disabled-list push button grayed out
1         Drop-down list enabled

Default: 1 (Enabled)


ΓòÉΓòÉΓòÉ 63.1.2. EXPRESSION ΓòÉΓòÉΓòÉ

This attribute may be set at open time, then modified and queried at any time.

It may be modified to the name of an ASL variable that will reflect the current
value of the DROPLIST control. If the variable is updated, then the value
displayed in the SLE part of DROPLIST changes in unison. If a new value is
typed or selected in the DROPLIST, then the ASL variable is updated. Values
returned to the ASL variable are limited in length to the current TEXTLIMIT
attribute value.

Modifying EXPRESSION replaces any prior modification of the VALUE attribute.


ΓòÉΓòÉΓòÉ 63.1.3. HANDLES ΓòÉΓòÉΓòÉ

Whether sizing handles are attached to the drop-down list to support moving,
sizing, and copying operations. These direct manipulation techniques follow the
CUA guidelines. See also the AUTOSELECT attribute of the WINDOW object.

0         Handles are not displayed
1         Handles are displayed

Default: 0 (No handles)


ΓòÉΓòÉΓòÉ 63.1.4. HELP ΓòÉΓòÉΓòÉ

Resource identifier (res ID) of the full help text for this object.

Default: 0


ΓòÉΓòÉΓòÉ 63.1.5. LISTREF ΓòÉΓòÉΓòÉ

This attribute may be set at open time, then modified and queried at any time.

It may be modified to the name of an ASL variable that will contain the
value(s) to be displayed in the LIST part of the DROPLIST. If the variable is
updated, the value(s) displayed in the LIST part of DROPLIST will change in
unison, truncated in length to the current TEXTLIMIT attribute value of
DROPLIST.

Modifying LISTREF replaces any prior setting of values made by the ITEMS
action.


ΓòÉΓòÉΓòÉ 63.1.6. ORIGIN ΓòÉΓòÉΓòÉ

The corner of the enclosing window to be taken as the origin. The position of
the drop-down list is measured from this point.

"TL"      Top left
"TR"      Top right
"BL"      Bottom left
"BR"      Bottom right

Default: "BL" (Bottom left)


ΓòÉΓòÉΓòÉ 63.1.7. SIZEX ΓòÉΓòÉΓòÉ

Width of the entry box, in dialog box units

Default: 0


ΓòÉΓòÉΓòÉ 63.1.8. SIZEY ΓòÉΓòÉΓòÉ

Height of the drop-down list, in dialog box units

Default: 0


ΓòÉΓòÉΓòÉ 63.1.9. VALUE ΓòÉΓòÉΓòÉ

This attribute may be set at open time, then modified and queried at any time.

When queried, VALUE returns the current value of the DROPLIST control. When
set, the current value of the DROPLIST control is set to the supplied value,
and that value appears in the TEXT part of the DROPLIST. The supplied value
does not have to exist in the current selection list. This allows a program to
supply an initial value that does not appear in the list. Once the user selects
an alternative value from the list, the initial value can only be reinstated by
the program.

Until VALUE is modified, or the user selects a value, it will return the
default value of a zero length character string when queried. Assignments to
this attribute will be truncated to the current TEXTLIMIT value.

Modifying VALUE removes any link to a variable established by the EXPRESSION
attribute.

No default


ΓòÉΓòÉΓòÉ 63.1.10. VISIBLE ΓòÉΓòÉΓòÉ

Whether the drop-down list is displayed:

0         Drop-down list not displayed
1         Drop-down list displayed

Default: 1 (Displayed)


ΓòÉΓòÉΓòÉ 63.1.11. X ΓòÉΓòÉΓòÉ

Horizontal position of the top left corner of the field, in dialog box units.

Default: 0


ΓòÉΓòÉΓòÉ 63.1.12. Y ΓòÉΓòÉΓòÉ

Vertical position of the bottom left corner of the field in dialog box units.

Default: 0


ΓòÉΓòÉΓòÉ 63.2. Actions ΓòÉΓòÉΓòÉ

EDIT()             ITEMS()


ΓòÉΓòÉΓòÉ 63.2.1. EDIT() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇEDIT(argument)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Enables the programmer to query whether a clipboard operation is supported and,
if it is, to carry it out.

argument is a clipboard query or a clipboard operation.

The following values for argument are used to check whether particular
clipboard operations can be supported with the drop-down list in its current
state:

"Querycut" Cut to clipboard
"Querycopy" Copy to clipboard
"Querypaste" Paste from clipboard
"Queryclear" Clear clipboard.

Where clipboard operations are supported, the following values for argument
direct them to be carried out:

"Cut"     Cut to clipboard
"Copy"    Copy to clipboard
"Paste"   Paste from clipboard
"Clear"   Clear clipboard.


ΓòÉΓòÉΓòÉ 63.2.2. ITEMS() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇITEMS(variable)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action populates the list of values. variable may be a scalar or a vector
containing the values to be used. Each invocation of the ITEMS action replaces
all existing items in the DROPLIST list.

The ITEMS action does not effect the SLE part of the DROPLIST control, or the
value returned from the VALUE attribute.

The list may contain values up to a length of 255 bytes. However, if a value
from the list is selected to populate the SLE, and its length is greater than
the current TEXTLIMIT, the value will be truncated prior to insertion in the
SLE. The VALUE attribute of the DROPLIST will return the truncated value.


ΓòÉΓòÉΓòÉ 63.3. Events ΓòÉΓòÉΓòÉ

DESKTOP            SELECT


ΓòÉΓòÉΓòÉ 63.3.1. DESKTOP ΓòÉΓòÉΓòÉ

Signaled when the drop-down list is moved, sized, or copied. A.System.Operation
is set to "MOVE", "SIZE", or "COPY". A.System.Object contains the name of the
control.


ΓòÉΓòÉΓòÉ 63.3.2. SELECT ΓòÉΓòÉΓòÉ

A SELECT event will occur whenever a value is selected from the list. When a
value is chosen using the keyboard, the SELECT event is deferred until the
DROPLIST loses focus, or the Enter key is pressed.

A.System.Object is set to named control.


ΓòÉΓòÉΓòÉ 63.4. Examples ΓòÉΓòÉΓòÉ

ON START
DO
  DECLARE CHARACTER[10] vector[15]
  DECLARE NUMERIC x
  DO x = 1 : vector[0]'ENTRIES
    LET vector[x] = STRING('Choice _',x)  ! Set vector of values
  END
  OPEN DROPLIST drop, win,                ! Open the DROPLIST
   X = 20, SIZEX = 60,
   Y = 50, SIZEY = 40
  CALL drop'ITEMS( vector )               ! Populate the DROPLIST
  LET drop'VALUE = vector[3]              ! Set initial value
END

ON SELECT
DO
  CASE A.System.Object
    WHEN 'T..drop'                        ! Event from the DROPLIST
      LET value = drop'VALUE              ! Get new selected value
    ...
  END
END

Examples source library:


ΓòÉΓòÉΓòÉ 63.5. More about DROPLIST ΓòÉΓòÉΓòÉ

o DROPLIST cannot be cloned.

o In a DBCS environment, a window containing a DROPLIST has a keyboard status
  line at the bottom for character conversion. This line is added
  automatically.

o The maximum number of rows which may be displayed in the list is typically
  400.


ΓòÉΓòÉΓòÉ 64. DURATION() ΓòÉΓòÉΓòÉ

The DURATION() function allows you to calculate the difference between two
dates or times, or to alter a date or time by a number of units.

ΓöÇΓöÇDURATION(expr1,expr2ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                         ΓööΓöÇ,typeΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÿ
                                 ΓööΓöÇ,periodΓöÇΓöÿ

Examples

More about DURATION()


ΓòÉΓòÉΓòÉ 64.1. Examples ΓòÉΓòÉΓòÉ

trip = DURATION(departure,arrival)


ΓòÉΓòÉΓòÉ 64.1.1. Difference between two dates ΓòÉΓòÉΓòÉ

The following examples assume that duedate is 25 February 1993, and that today
is 20 December 1992:

DECLARE DATE duedate = DATE( '25th February 1994' )
DECLARE DATE today   = DATE( '20th December 1993' )
DECLARE DATE late    = DATE( ' 1st March    1994' )
DECLARE DATE jan1    = DATE( ' 1st January  1993' )

x = DURATION( today, duedate )          !  67 days
x = DURATION( late , duedate )          !  -4 days
x = DURATION( today, duedate, "M" )     !   2 months
x = DURATION( today, duedate, "Y" )     !   0 years
x = DURATION( today, duedate, "P", 2 )  ! 134 half-days
x = DURATION( jan1 , today  , "W" )     !  50 weeks


ΓòÉΓòÉΓòÉ 64.1.2. Adding and subtracting a value to and from a date ΓòÉΓòÉΓòÉ

The following example assumes that xdate is 25 February 1993:

DECLARE DATE today = DATE( '6th May 1994' )

x = DURATION( today, 10 )               ! 16th May 1994
x = DURATION( today,  1, "M" )          !  6th Jun 1994
x = DURATION( today, 15, "M" )          !  6th Aug 1995
x = DURATION( today, -1, "M" )          !  6th Apr 1994
x = DURATION( today,  3, "Y" )          !  6th May 1997
x = DURATION( today, 12, "P", 3 )       ! 10th May 1994, period 0
x = DURATION( today, 36, "P", 24 )      !  7th May 1994, period 12

The following example assumes that xdate is 31 January 1993:

LET newdate=DURATION(xdate,1,"M")
                         !  newdate = 28 February 1993.

The following example assumes that xdate is 28 February 1993:

LET newdate=DURATION(xdate,-1,"M")
                         !  newdate = 28 January 1993.

The following example assumes that xdate is 31 January 1991:

LET newdate=DURATION(xdate,3,"Y")
                         !  newdate = 31 January 1994.

The following example assumes that xdate is period 0 of 25 February 1993:

LET newdate=DURATION(xdate,"12","P",3)
                         !  newdate = 1 March 1993.

The following example assumes that xdate is period 0 of 25 February 1993:

LET newdate=DURATION(xdate,"12","P",24)
              !  newdate = period 12 of 25 February 1993.

Examples source library:


ΓòÉΓòÉΓòÉ 64.2. More about DURATION() ΓòÉΓòÉΓòÉ

o Time results greater than 23:59:59 and expressed in hours, minutes and
  seconds, are adjusted to give a time in the following day.

o Adding and subtracting month units might yield a date that does not exist
  (for example, adding one month to January 31 suggests that February 31 should
  be returned). In this case (as in the examples quoted above), the nearest
  valid date in the appropriate month is returned (February 28 or 29 if one
  month is added to January 31). Note that:

    ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
    ΓöéThis:           ΓöéAdjusted by:    ΓöéReturns:                Γöé
    Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
    ΓöéMarch 31        Γöé-1 month        ΓöéFebruary 28 (or 29)     Γöé
    Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
    ΓöéFebruary 28     Γöé+1 month        ΓöéMarch 28                Γöé
    Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
    ΓöéFebruary 28     Γöé-1 month        ΓöéJanuary 28              Γöé
    Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
    ΓöéMarch 31        Γöé-2 months       ΓöéJanuary 31              Γöé
    ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

o The DURATION() function uses the Gregorian calendar. No account is taken of
  the various changeovers from the Julian calendar.

o If the number of periods in either specified date exceeds period, then an
  error will occur.

o A result which could be before year 1 or after year 9999 will produce an
  error.


ΓòÉΓòÉΓòÉ 65. ELLIPSE ΓòÉΓòÉΓòÉ

The ELLIPSE graphics primitive object class creates an instance of an ellipse.

Parent: DEFINE

Attributes

Actions: None.

Events: None.


ΓòÉΓòÉΓòÉ 65.1. Attributes ΓòÉΓòÉΓòÉ

REFERENCE            TILT

The following standard graphics attributes are also available. See
Standard graphics attributes.

BOUNDED                FILLCOLOR
LINEWIDTH              SELECTED
COLOR                  FILLPATTERN
MIX                    VISIBLE
CONSTANT               LINESTYLE
SELECTABLE


ΓòÉΓòÉΓòÉ 65.1.1. REFERENCE ΓòÉΓòÉΓòÉ

Vector defining the ellipse. This vector consists of the following elements:

1         X coordinate of the center of the ellipse
2         Y coordinate of the center of the ellipse
3         length of the X axis of the ellipse
4         length of the Y axis of the ellipse.

All coordinates are in world coordinate units.

Set on OPEN, then read-only.

Default: ""


ΓòÉΓòÉΓòÉ 65.1.2. TILT ΓòÉΓòÉΓòÉ

Angle at which the ellipse is tilted. The angle of tilt is specified in degrees
and is measured counterclockwise from the horizontal.

Default: 0 (No tilt)


ΓòÉΓòÉΓòÉ 66. ELSE ΓòÉΓòÉΓòÉ

The ELSE statement introduces a set of statements to be executed if the
condition given by an IF statement is not met. ELSE can only be used in
conjunction with the IF statement.

ΓöÇΓöÇELSEΓöÇΓöÇstatementlistΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Examples

More about ELSE

See also: IF ... THEN ... ELSE, THEN


ΓòÉΓòÉΓòÉ 66.1. Examples ΓòÉΓòÉΓòÉ

IF OK
  CALL UPDATE()
ELSE DO
  IF Status = 'Open'
  CALL RESTORE()
END

IF Code = 'Write' & Status = 'Open'
THEN CALL OVERWRITE()
ELSE CALL REINSTATE()

Examples source library:


ΓòÉΓòÉΓòÉ 66.2. More about ELSE ΓòÉΓòÉΓòÉ

o ELSE can be followed by a single statement or multiple statements. Multiple
  statements must be enclosed in a DO ... END block.

o The single statement of an ELSE clause, or the DO statement of a DO ... END
  block, can appear on the same line as the ELSE, or on the following line.

o If the condition specified on the IF statement is NULL, then the ELSE block
  executes.


ΓòÉΓòÉΓòÉ 67. END ΓòÉΓòÉΓòÉ

The END statement denotes the end of a block of statements, the start of which
is denoted by a DO statement.

The END statement also ends a CASE statement.

ΓöÇΓöÇENDΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

More about END

See also: CASE...WHEN...OTHERWISE...END, DO...END, WHILE


ΓòÉΓòÉΓòÉ 67.1. More about END ΓòÉΓòÉΓòÉ

o For every DO statement, there must be an END statement.

o For every CASE statement, there must be an END statement.

o In a repeating DO block where processing is not yet complete, END passes
  control back to the top of the block.

o If the END statement occurs at the end of an event block, the program goes
  into a wait state.


ΓòÉΓòÉΓòÉ 68. ENTRIES() ΓòÉΓòÉΓòÉ

The ENTRIES() function returns the number of entries in an array or table.

ΓöÇΓöÇENTRIES(reference)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Examples

More about ENTRIES()


ΓòÉΓòÉΓòÉ 68.1. Examples ΓòÉΓòÉΓòÉ

PROCEDURE average(column)
DO
  DECLARE CHAR[20] column

  /* Find the average numeric value in a column.                       */
  /* Count an entry zero if it is NULL or is not numeric.              */
  /* Return NULL (and display a message) if the column does not exist. */
  /* The TOTAL() function can be used to get the column total, so this */
  /*  example just demonstrates an alternative way of doing that.      */

  DECLARE NUMERIC items = ENTRIES("MyTab." || column)

  DECLARE CLEAR NULL NUMERIC result
  DECLARE NUMERIC i
  DECLARE NULL NUMERIC nextitem

  IF items = -1
  THEN MESSAGE "FTB10003", 0, STRING("Column ^ does not exist", column)
  ELSE DO
    LET result = 0
    DO i = 1 : items
      FORGIVE LET nextitem = (?("MyTab." || column))[i]
      IF A.System.ErrorNumber = 0 & \NULL(nextitem)
        LET result += nextitem
    END
    LET result /= items
  END

  RETURN result
END

Examples source library:


ΓòÉΓòÉΓòÉ 68.2. More about ENTRIES() ΓòÉΓòÉΓòÉ

o Where reference is a column in a table, ENTRIES() returns the equivalent of
  the number of rows in the table.

o Where reference does not belong to a table, ENTRIES() returns the number of
  elements in the array. In the case of a two-dimensional array, this number is
  the product of the number of elements in each dimension.

o If reference does not exist, then ENTRIES() returns -1.

o Where reference is the name of a variable, the name should be enclosed by
  quotation marks ("") to prevent the variable being created if it does not
  already exist. If the variable is known to exist, then the ENTRIES attribute
  is simpler and more efficient:

    LET number_of_strings = StringArray[0]'ENTRIES
    LET items = MyTab.AnnualSalary[0]'ENTRIES

  Note that using StringArray in this way causes the variable to be created if
  it does not exist.


ΓòÉΓòÉΓòÉ 69. ENTRY ΓòÉΓòÉΓòÉ

The ENTRY object class creates an instance of a multi-line entry field (MLE).

Parent: WINDOW

Attributes

Actions

Events

Examples

More about ENTRY


ΓòÉΓòÉΓòÉ 69.1. Attributes ΓòÉΓòÉΓòÉ

ANCHORX                ANCHORY
AUTOREFRESH            BGCOLOR
BORDER                 CLONEDIR
CLONEGAP               CLONES
CURSORX                CURSORY
EXPRESSION             FGCOLOR
FIRSTCHAR              FIXEDFONT
HANDLES                HELP
HORZSCROLL             MODE
ORIGIN                 ORIGINX
ORIGINY                SELECTABLE
SIZEX                  SIZEY
TABACTION              TEXTLIMIT
VERTSCROLL             VISIBLE
WORDWRAP               X
Y


ΓòÉΓòÉΓòÉ 69.1.1. ANCHORX ΓòÉΓòÉΓòÉ

Current horizontal position in the text of the start of a marked block,
measured relative to the position of the start of the text block.  An integer.

Default: Calculated by Presentation Manager* services.


ΓòÉΓòÉΓòÉ 69.1.2. ANCHORY ΓòÉΓòÉΓòÉ

Current vertical position in the text of the start of a marked block, measured
relative to the position of the start of the text block.  An integer.

Default: Calculated by Presentation Manager services.


ΓòÉΓòÉΓòÉ 69.1.3. AUTOREFRESH ΓòÉΓòÉΓòÉ

Refreshes the data used in the MLE when the underlying data in the variable
changes:

0         Autorefresh off
1         Autorefresh on

Default: 1 (On)


ΓòÉΓòÉΓòÉ 69.1.4. BGCOLOR ΓòÉΓòÉΓòÉ

Background color. Integer in the range 1-19. See Colors and color codes for
details of colors available.

Default: System window background color


ΓòÉΓòÉΓòÉ 69.1.5. BORDER ΓòÉΓòÉΓòÉ

Draws a border around a field:

0         No border drawn
1         Border drawn

Default: 0 (No border drawn)


ΓòÉΓòÉΓòÉ 69.1.6. CLONEDIR ΓòÉΓòÉΓòÉ

Direction in which the clones are laid out:

1         Down
2         Up
3         Left
4         Right.

Set on OPEN, then read-only.

Default: 1 (Down)


ΓòÉΓòÉΓòÉ 69.1.7. CLONEGAP ΓòÉΓòÉΓòÉ

Space between clones, in dialog units.

Set on OPEN, then read-only.

Default: 0


ΓòÉΓòÉΓòÉ 69.1.8. CLONES ΓòÉΓòÉΓòÉ

Number of clones.

Default: 1


ΓòÉΓòÉΓòÉ 69.1.9. CURSORX ΓòÉΓòÉΓòÉ

Current horizontal position in the text of the end of a marked block, measured
relative to the position of the start of the text block.  An integer.

Default: Calculated by Presentation Manager services.


ΓòÉΓòÉΓòÉ 69.1.10. CURSORY ΓòÉΓòÉΓòÉ

Current vertical position in the text of the end of a marked block, measured
relative to the position of the start of the text block.  An integer.

Default: Calculated by Presentation Manager services.


ΓòÉΓòÉΓòÉ 69.1.11. EXPRESSION ΓòÉΓòÉΓòÉ

Pointer to a variable containing data to be displayed by the MLE. If the named
variable is element [1] of an array, each element of the array is also
displayed on a separate line of the entry field.

Default: ""


ΓòÉΓòÉΓòÉ 69.1.12. FGCOLOR ΓòÉΓòÉΓòÉ

Foreground color. Integer in the range 1-19. See Colors and color codes for
details of colors available.

Default: System window text color


ΓòÉΓòÉΓòÉ 69.1.13. FIRSTCHAR ΓòÉΓòÉΓòÉ

Offsets the entry field to the left by a number of characters. The value of
FIRSTCHAR is the number of obscured bytes in the string. For SBCS environments,
this is the same as the number of characters obscured.  However, if there are
any obscured DBCS characters in the string, this relationship does not apply.

An error results if the number specified is greater than the number of
characters.

Default: 0


ΓòÉΓòÉΓòÉ 69.1.14. FIXEDFONT ΓòÉΓòÉΓòÉ

Font to use:

0         System font
1         Courier point size 10

Default: 0 (System font)


ΓòÉΓòÉΓòÉ 69.1.15. HANDLES ΓòÉΓòÉΓòÉ

Whether sizing handles are attached to the MLE to support moving, sizing, and
copying operations. These direct manipulation techniques follow the CUA
guidelines. See also the AUTOSELECT attribute of the WINDOW object.

0         Handles are not displayed
1         Handles are displayed

Default: 0 (No handles)


ΓòÉΓòÉΓòÉ 69.1.16. HELP ΓòÉΓòÉΓòÉ

Resource identifier (res ID) of the full help text for this entry field.

Default: None


ΓòÉΓòÉΓòÉ 69.1.17. HORZSCROLL ΓòÉΓòÉΓòÉ

Horizontal scroll bar drawn to enable data scrolling:

0         No horizontal scroll bar drawn
1         Horizontal scroll bar drawn
Set on OPEN, then read-only.

Default: 0 (No horizontal scroll bar drawn)


ΓòÉΓòÉΓòÉ 69.1.18. MODE ΓòÉΓòÉΓòÉ

Specifies what operations the user can carry out on text in the entry field:

0         Static - text cannot be moved
1         Display - text can be scrolled
2         Modifiable - text can be edited

Default: 2 (Modifiable)


ΓòÉΓòÉΓòÉ 69.1.19. ORIGIN ΓòÉΓòÉΓòÉ

The corner of the enclosing window to be taken as the origin. The position of
the entry field is measured from this point.

"TL"      Top left
"TR"      Top right
"BL"      Bottom left
"BR"      Bottom right

Default: "BL" (Bottom left)


ΓòÉΓòÉΓòÉ 69.1.20. ORIGINX ΓòÉΓòÉΓòÉ

Current horizontal position in the text of the character displayed at the top
left corner of the MLE measured relative to the position of the start of the
text block.  An integer.

Default: Calculated by Presentation Manager services.


ΓòÉΓòÉΓòÉ 69.1.21. ORIGINY ΓòÉΓòÉΓòÉ

Current vertical position in the text of the character displayed at the top
left corner of the MLE measured relative to the position of the start of the
text block.  An integer.

Default: Calculated by Presentation Manager services.


ΓòÉΓòÉΓòÉ 69.1.22. SELECTABLE ΓòÉΓòÉΓòÉ

Whether the entry field is selectable:

0         Entry field not selectable
1         Entry field selectable

Default: 0 (Not selectable)


ΓòÉΓòÉΓòÉ 69.1.23. SIZEX ΓòÉΓòÉΓòÉ

Width, in dialog box units.

Default: None


ΓòÉΓòÉΓòÉ 69.1.24. SIZEY ΓòÉΓòÉΓòÉ

Height, in dialog box units.

Default: None


ΓòÉΓòÉΓòÉ 69.1.25. TABACTION ΓòÉΓòÉΓòÉ

Specifies the action taken when the ENTRY object receives a Tab keystroke:

"IGNORE"  (Default.) Tab is ignored. Shift-Tab is ignored.

"INSERT"  Tab inserts a TAB character. Shift-Tab is ignored.

"EXIT"    Tab moves to the next control. Shift-Tab moves to the previous
          control.

Ctrl-TAB moves to the next control, whatever the setting.

Default: "IGNORE"


ΓòÉΓòÉΓòÉ 69.1.26. TEXTLIMIT ΓòÉΓòÉΓòÉ

Maximum number of bytes allowed in this entry field. If set to -1, the limit is
unbounded.

Default: 65535


ΓòÉΓòÉΓòÉ 69.1.27. VERTSCROLL ΓòÉΓòÉΓòÉ

Vertical scroll bar drawn to enable data scrolling:

0         No vertical scroll bar drawn
1         Vertical scroll bar drawn
Set on OPEN, then read-only.

Default: 0 (No vertical scroll bar drawn)


ΓòÉΓòÉΓòÉ 69.1.28. VISIBLE ΓòÉΓòÉΓòÉ

Whether the entry field is displayed:

0         Entry field not displayed
1         Entry field displayed

Default: 1 (Displayed)


ΓòÉΓòÉΓòÉ 69.1.29. WORDWRAP ΓòÉΓòÉΓòÉ

Wraps line round if it goes off the right-hand edge of the entry field:

0         Wordwrap disabled
1         Wordwrap enabled
When text is wrapped to a new line, the original array element is used to hold
the wrapped text. Otherwise, when there is no wordwrap, each line goes into its
own element.

Default: 0 (Disabled)


ΓòÉΓòÉΓòÉ 69.1.30. X ΓòÉΓòÉΓòÉ

Horizontal position within the window, in dialog box units.

Default: 0


ΓòÉΓòÉΓòÉ 69.1.31. Y ΓòÉΓòÉΓòÉ

Vertical position within the window, in dialog box units.

Default: 0


ΓòÉΓòÉΓòÉ 69.2. Actions ΓòÉΓòÉΓòÉ

EDIT()               REFRESH()


ΓòÉΓòÉΓòÉ 69.2.1. EDIT() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇEDIT(argument)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Enables the programmer to query whether a clipboard operation is supported and,
if it is, to carry it out.

argument is a clipboard query or a clipboard operation.

The following values for argument are used to check whether particular
clipboard operations can be supported with the entry field in its current
state:

"Querycut" Cut to clipboard
"Querycopy" Copy to clipboard
"Querypaste" Paste from clipboard
"Queryclear" Clear clipboard.
Where clipboard operations are supported, the following values for argument
direct them to be carried out:

"Cut"     Cut to clipboard
"Copy"    Copy to clipboard
"Paste"   Paste from clipboard
"Clear"   Clear clipboard.


ΓòÉΓòÉΓòÉ 69.2.2. REFRESH() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇREFRESH()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Forces repainting of the entry field on screen.


ΓòÉΓòÉΓòÉ 69.3. Events ΓòÉΓòÉΓòÉ

DATA               DESKTOP


ΓòÉΓòÉΓòÉ 69.3.1. DATA ΓòÉΓòÉΓòÉ

Signaled when another object is selected and data has changed. A.System.Object
is set to the name of the entry field. A.System.Boxnumber is set to the clone
selected.


ΓòÉΓòÉΓòÉ 69.3.2. DESKTOP ΓòÉΓòÉΓòÉ

Signaled when the MLE is moved, sized, or copied. A.System.Operation is set to
"MOVE", "SIZE", or "COPY". A.System.Object contains the name of the control.


ΓòÉΓòÉΓòÉ 69.4. Examples ΓòÉΓòÉΓòÉ

!
! Open a multiline entry control on a window
!
PROCEDURE OpenEntry(pWindow)
DO
  DECLARE POINTER pWindow
  !
  ! define some sample text
  !
  DEFINE entrytext[0]
  INSERT entrytext[0] = 'Mary had a little lamb'
  INSERT entrytext[0] = 'Its fleece was white as snow'
  INSERT entrytext[0] = 'And everywhere that Mary went'
  INSERT entrytext[0] = 'The lamb was sure to go'

  OPEN ENTRY entry1, ?pWindow,
   X = 20, Y = 20,                ! position
   SIZEX = 150, SIZEY = 150,      ! size
   EXPRESSION = 'entrytext[1]',   ! referenced array
   WORDWRAP = 0,                  ! turn off word-wrap
   SELECTABLE = 1,                ! make it selectable
   ORIGIN = 'BL',                 ! origin bottom left (the default)
   VISIBLE = 1,                   ! make it visible (the default)
   MODE = 2,                      ! 0=static,
                                  ! 1=display only,
                                  ! 2=modifiable (the default)
   AUTOREFRESH = 1                ! set it to automatically refresh
END

Examples source library:


ΓòÉΓòÉΓòÉ 69.5. More about ENTRY ΓòÉΓòÉΓòÉ

o If there are no clones (CLONES=1), each element of the vector identified in
  the REFERENCE is mapped to each row within the entry field.

o The following attributes can only be modified for the entire clone set, not
  for the individual clones:

   CLONEDIR
   CLONEGAP
   CLONES
   HANDLES

o In a DBCS environment, a window containing an ENTRY has a keyboard status
  line at the bottom for character conversion. This line is added
  automatically.

o The slider on an MLE, like the slider on a LIST box, is handled by the MLE
  itself. ENTRY does not signal a SCROLL event when the slider is moved.


ΓòÉΓòÉΓòÉ 70. ERROR ΓòÉΓòÉΓòÉ

The ERROR statement displays messages on the screen. The text of the message is
displayed in a pop-up window together with a visual cue.

ΓöÇΓöÇERRORΓöÇΓöÇnumber,messagetextΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                               Γöé <ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ Γöé
                               ΓööΓöÇΓöÇ,parameterΓö┤ΓöÇΓöÿ

Examples

More about ERROR

See also: DIALOG(), MESSAGE, STRING(), WINDOW


ΓòÉΓòÉΓòÉ 70.1. Examples ΓòÉΓòÉΓòÉ

LET foo = "Freddy"
LET bar = "message"

ERROR 1, "Simple text string message with an information sign"
ERROR 2, "Concatenated ", bar, " displaying a warning sign"
ERROR 3, 'Message including two expressions: _ and _', 2*3*4, foo
ERROR 10002, "Warning message without a prefix"

Examples source library:


ΓòÉΓòÉΓòÉ 70.2. More about ERROR ΓòÉΓòÉΓòÉ

o messagetext can contain underscore (_) or caret (^) characters. These are
  replaced in the string which is built by ERROR. A maximum of ten
  substitutions may be made. See STRING() for more information on
  substitutions.

  Underscore inserts the expression into messagetext without quotes. Caret
  causes the expression to be surrounded by single quotes before it is
  inserted.

    ERROR 1, "Name ^, Age _, Spare: ", foo, 2*3*4, "baloney"

o See MESSAGE for a statement that displays a message on the screen.

o See DIALOG() for a function that displays a message and returns a code
  representing the push button that the end user presses.


ΓòÉΓòÉΓòÉ 71. EVALUATE() ΓòÉΓòÉΓòÉ

The EVALUATE() function compiles an expression to generate an object code
variable that can then be executed by the  ? operator. This is used to evaluate
expressions that are not known until run time.

ΓöÇΓöÇEVALUATE(ΓöÇexpressionΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Examples

More about EVALUATE()

See also: POINTER()

Also see Operators.


ΓòÉΓòÉΓòÉ 71.1. Examples ΓòÉΓòÉΓòÉ

DECLARE CHAR[*] expression = "(123.4 * 0.74) / 1.17"
DECLARE UNTYPED compiled_expression = EVALUATE(expression)
DECLARE UNTYPED root

MESSAGE 'FTB10002', 0, STRING("result is _", ?compiled_expression)
LET Root = EVALUATE("SQRT(1234)")   ! ?Root will give 35.13

The following example sets up a search expression based on a changeable column
and a choice of conditions.  It then searches on these. Notice that the ?
operator is used to evaluate the expression following it.

DECLARE NUMERIC required

DECLARE CHAR[2] operation = IF(required, "=", "<=")
DECLARE UNTYPED findit = EVALUATE(STRING("(?pcolumn)[i] _ findthis", operation))

DO i = 1 : (?pcolumn)[0]'ENTRIES
  IF ?findit
  THEN DO
    ...

Examples source library:


ΓòÉΓòÉΓòÉ 71.2. More about EVALUATE() ΓòÉΓòÉΓòÉ

o An expression inside an EVALUATE() function does not have access to the
  procedures, the functions, or the declared variables of the invoking routine.

o An evaluated expression cannot occur inside another evaluated expression.


ΓòÉΓòÉΓòÉ 72. EXP() ΓòÉΓòÉΓòÉ

The EXP() function is the exponential function. EXP() returns the value of the
base raised to a specified power.

ΓöÇΓöÇEXP(ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇexpressionΓöÇΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
          ΓööΓöÇbase,ΓöÇΓöÿ

Examples

More about EXP()


ΓòÉΓòÉΓòÉ 72.1. Examples ΓòÉΓòÉΓòÉ

LET x = EXP(100,2)               ! result is 10000
LET y = EXP(-1)                  ! result is 0.37   (which is 1/e)
LET z = EXP(-3, 4)               ! result is 81

Examples source library:


ΓòÉΓòÉΓòÉ 72.2. More about EXP() ΓòÉΓòÉΓòÉ

o A nonnumeric value causes an error.
o A negative number raised to any noninteger power causes an error.


ΓòÉΓòÉΓòÉ 73. EXTRACTGLOBAL() ΓòÉΓòÉΓòÉ

The EXTRACTGLOBAL() function identifies the global values in a string.

                          ΓöîΓöÇ"@"ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöÇΓöÇEXTRACTGLOBAL(string,ΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                          ΓööΓöÇtriggerΓöÇΓöÿ

Examples

More about EXTRACTGLOBAL()

See also: GLOBAL(), REPLACEGLOBAL()


ΓòÉΓòÉΓòÉ 73.1. Examples ΓòÉΓòÉΓòÉ

LET list1 = EXTRACTGLOBAL("It is @Month @Year")
! list1 is "       Month  Year"
LET list2 = EXTRACTGLOBAL("It is @@Month")
! list2 is "            "
LET list3 = EXTRACTGLOBAL("SELECT @columns FROM &table", "@&")
! list3 is "        columns       table"

Examples source library:


ΓòÉΓòÉΓòÉ 73.2. More about EXTRACTGLOBAL() ΓòÉΓòÉΓòÉ

o If the characters following a trigger do not correspond to the name of a
  global value, blanks are returned.

o The name stops at the first blank or other separator.

o The sequence @@ will produce a single @ and does not introduce a global
  value.


ΓòÉΓòÉΓòÉ 74. FACTORIAL() ΓòÉΓòÉΓòÉ

The FACTORIAL() function returns the factorial of a number.

ΓöÇΓöÇFACTORIAL(number)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Examples


ΓòÉΓòÉΓòÉ 74.1. Examples ΓòÉΓòÉΓòÉ

LET x = FACTORIAL(5)       !  Result is 120
LET y = FACTORIAL(10.5)    !  Result is 3628800   (Input truncated)

Examples source library:


ΓòÉΓòÉΓòÉ 75. FAIL ΓòÉΓòÉΓòÉ

The FAIL statement causes the executing task to RETURN, and the task which
invoked it to have ERROR raised.  ERROR will have the message number and the
optional fill.

ΓöÇΓöÇFAILΓöÇΓöÇnumberΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                  ΓööΓöÇ,fillΓöÇΓöÿ

Examples

More about FAIL

See also: FORGIVE, ON


ΓòÉΓòÉΓòÉ 75.1. Examples ΓòÉΓòÉΓòÉ

FAIL A.System.ErrorNumber, A.System.ErrorInfo   ! Pass error to caller

PROCEDURE SetKeynames()
DO
  IF \NULL(keynames)
  THEN FAIL 2880, "SetKeynames"
  ...

Examples source library:


ΓòÉΓòÉΓòÉ 75.2. More about FAIL ΓòÉΓòÉΓòÉ

o The caller may control the error by using the FORGIVE or ON ERROR statements,
  otherwise the error will result in the normal pop-up message.

o FAIL is only meaningful in synchronous events (START, RUN, QUERY, and any
  event signaled by RUN PROGRAM). If the executing task was not invoked in this
  way, FAIL causes the error to be signaled to itself.


ΓòÉΓòÉΓòÉ 76. FALSE ΓòÉΓòÉΓòÉ

The FALSE statement identifies a particular value of a CASE expression. When
the expression takes on a value of 0, the statement following FALSE is
executed.

ΓöÇΓöÇFALSEΓöÇΓöÇstatementlistΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Examples

More about FALSE

See also: CASE...WHEN...OTHERWISE...END, IF ... THEN ... ELSE, NULL, TRUE


ΓòÉΓòÉΓòÉ 76.1. Examples ΓòÉΓòÉΓòÉ

X = 11
Y = 10
CASE X < Y
  TRUE
    MESSAGE "FTB0001",0,"2 - True ..."
  FALSE
    MESSAGE "FTB0001",0,"2 - False ..."
  NULL
    MESSAGE "FTB0001",0,"2 - Null ..."
  ! Note that "IF x < y ... ELSE DO ..." will run the ELSE part
  ! when the expression is FALSE but also when the expression is NULL
  ! (which would arise if X or Y or both were NULL)
END

Examples source library:


ΓòÉΓòÉΓòÉ 76.2. More about FALSE ΓòÉΓòÉΓòÉ

o CASE...TRUE...FALSE...NULL...END performs a three-way test which takes
  account of NULL values. The IF statement performs a two-way test which is
  equivalent to CASE...TRUE...OTHERWISE...END.

o If a CASE expression is not present, any TRUE, FALSE, or NULL blocks are
  ignored.


ΓòÉΓòÉΓòÉ 77. FILE ΓòÉΓòÉΓòÉ

The FILE object class provides access to OS/2 files.

Attributes

Actions

Examples

More about FILE

More about FILE'GET()

More about FILE'PUT()

See also: LINE(), PAGE(), POSITION(), SPACE(), TAB()


ΓòÉΓòÉΓòÉ 77.1. Attributes ΓòÉΓòÉΓòÉ

ACCESS              CODE
CONVERT             EOF
FORMAT              LENGTH
LOCATION            MODE
NAME                POINT


ΓòÉΓòÉΓòÉ 77.1.1. ACCESS ΓòÉΓòÉΓòÉ

Describes the way in which the file will be processed:

"SEQ"     Sequential access
"RANDOM"  Random access
"MIXED"   Mostly, but not only, sequential access

Set on OPEN, then read-only

Default: "SEQ"


ΓòÉΓòÉΓòÉ 77.1.2. CODE ΓòÉΓòÉΓòÉ

Most recent OS/2 error code.

Can be queried but not modified.

Default: None


ΓòÉΓòÉΓòÉ 77.1.3. CONVERT ΓòÉΓòÉΓòÉ

Conversion required:

"ASCII"   Convert to ASCII
"EBCDIC"  Convert to EBCDIC code page 939
"K-HOST"  Convert to EBCDIC code page 930.
When in a Japanese operating environment, "EBCDIC" converts to code page 939 of
EBCDIC called SAA Code page (Extended 931). If you want to access Katakana or
Alphabets, convert to code page 930 of EBCDIC and use "K-HOST" for the CONVERT
attribute.

Only applies to FILE objects where the FORMAT attribute is "BINARY"

Set on OPEN, then read-only.

Default: "ASCII"


ΓòÉΓòÉΓòÉ 77.1.4. EOF ΓòÉΓòÉΓòÉ

Whether the end of an input file has been reached:

0         EOF not yet reached
1         EOF reached

EOF is normally queried.  It can be modified, but only to 1.

Default: None


ΓòÉΓòÉΓòÉ 77.1.5. FORMAT ΓòÉΓòÉΓòÉ

Format of the file:

"TEXT"    ASCII format
"BINARY"  Binary format

Set on OPEN, then read-only.

Default: "TEXT"


ΓòÉΓòÉΓòÉ 77.1.6. LENGTH ΓòÉΓòÉΓòÉ

Length, in characters, to be used for the next record read (BINARY files), or
as a limit for the length (TEXT files).

LENGTH can be queried or modified. If modified, it sets the length of the next
record read.

Default: 255


ΓòÉΓòÉΓòÉ 77.1.7. LOCATION ΓòÉΓòÉΓòÉ

Location of the file (its OS/2 path)

Set on OPEN, then read-only.

Default: None


ΓòÉΓòÉΓòÉ 77.1.8. MODE ΓòÉΓòÉΓòÉ

Access mode:

"READ"    Read-only
"WRITE"   Write-only
"APPEND"  WRITE at end of file

Set on OPEN, then read-only.

Default: "READ"


ΓòÉΓòÉΓòÉ 77.1.9. NAME ΓòÉΓòÉΓòÉ

Name of the operating system file (file name and extension)

Set on OPEN, then read-only.

Default: None


ΓòÉΓòÉΓòÉ 77.1.10. POINT ΓòÉΓòÉΓòÉ

Current point within the file.  An integer.

POINT can be queried or modified. If modified, it alters the current position
in the file, in terms of characters from the start.

Default: None


ΓòÉΓòÉΓòÉ 77.1.11. OBJECTCLASS ΓòÉΓòÉΓòÉ

External class name of the object. Refers to the .TYPE extended attribute of
the OS/2 file that the object is held as. It is used by Visualizer for the
objects it creates.

Set on OPEN, then read-only.


ΓòÉΓòÉΓòÉ 77.2. Actions ΓòÉΓòÉΓòÉ

COPYEATTRS()            GET()
PUT()                   SAVETO()


ΓòÉΓòÉΓòÉ 77.2.1. COPYEATTRS() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇCOPYEATTRS(object)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Copies the extended attributes from another object. Only OS/2 file-based
objects have extended attributes.


ΓòÉΓòÉΓòÉ 77.2.2. GET() ΓòÉΓòÉΓòÉ

             <ΓöÇ,ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöÇΓöÇGET(var1ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼Γö┤ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
              ΓööΓöÇvar2ΓöÇΓöÿ

GET() reads data from the file. Up to ten variables can be supplied as
arguments. Whole arrays can be read using [0]. TEXT file records must be
separated by carriage return and line feed character pairs. BINARY file record
length is set by the LENGTH attribute.


ΓòÉΓòÉΓòÉ 77.2.3. PUT() ΓòÉΓòÉΓòÉ

             <ΓöÇ,ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöÇΓöÇPUT(exp1ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼Γö┤ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
              ΓööΓöÇexp2ΓöÇΓöÿ

PUT() adds to the file the string resulting from an expression. Up to ten
expressions can be supplied as arguments to PUT(). Whole arrays can be
specified using [0].


ΓòÉΓòÉΓòÉ 77.2.4. SAVETO() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSAVETO(OS2_filename))ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Saves the FILE data as a new OS/2 file.


ΓòÉΓòÉΓòÉ 77.3. Examples ΓòÉΓòÉΓòÉ

! Procedure which makes use of the file object. A temporary file
! name has been identified by the system procedure. This
! procedure manipulates that file.
!
PROCEDURE file(tempname)
DO
  DECLARE CHAR[*] tempname

  DECLARE NUMERIC i

  OPEN FILE writeout,
   NAME     = NAME(tempname),
   LOCATION = LOCATION(tempname),
   MODE     = 'WRITE'
  !
  ! write out the contents of "days" vector to the file
  ! LINE() starts a new line
  !
  DO i = 1 : days[0]'ENTRIES
    CALL writeout'PUT(days[i], LINE())
  END
  !
  ! delete contents of "days" vector and close the file
  !
  CLEAR days
  SHUT writeout
  !
  ! open the file (in read mode)
  !
  OPEN file readin,
   NAME     = name(tempname),
   LOCATION = location(tempname),
   MODE     = 'READ'
  !
  ! read the contents of the file back into the "days" vector
  !
  CALL readin'GET(days[0])
  SHUT readin
END

Examples source library:


ΓòÉΓòÉΓòÉ 77.4. More about FILE ΓòÉΓòÉΓòÉ

o OS/2 errors are noted in the CODE attribute of the FILE. Only the most recent
  error is available in this attribute.

o OPEN FILE always opens a FILE object, even if it cannot open the file itself.
  So FILE objects should always be SHUT. This means that if you have used OPEN
  FILE on a file that cannot be opened, you can read the CODE attribute to see
  what happened.  But all operations on a FILE object in this state which refer
  to the file itself are disallowed.

o When a text-format file is shut using the SHUT statement, a Control-Z
  character is output to mark the end of the file.


ΓòÉΓòÉΓòÉ 77.5. More about FILE'GET() ΓòÉΓòÉΓòÉ

o If the variable given as an argument to GET() is an indexed array reference,
  with index greater than 0, then the FILE data is put into that element of the
  array.

o If the variable is an array reference, with index 0, then the whole array is
  filled with data from the file.

o If the first or second dimension of the array is defined as zero, then GET()
  reads all the remaining records from the file and places them in successive
  rows of the array.  GET() resizes the first dimension of the array to equal
  the number of records it reads.

o If the first dimension of the array has a size n (greater than zero), and the
  second dimension is omitted or greater than zero, then GET() reads up to n
  records from the file and places them in successive rows of the array. If
  there are insufficient records to fill all the rows, then unfilled rows have
  a value of NULL data type.

o If the record has only one dimension, then GET() truncates any records longer
  than the current LENGTH. The excess data is not stored.

o If a TEXT record length exceeds 255 bytes and the array has two dimensions,
  then GET() splits the record and places the data in successive columns of the
  appropriate row, beginning at column one. Each array column is filled, and
  any columns of that row that are not used are assigned a data type of NULL.

o If the second dimension of the array is defined as zero, then GET() redefines
  it so that there are sufficient columns of up to 254 bytes each to hold the
  longest record read.

o If the second dimension of the array has a size n, then GET() truncates any
  records longer than LENGTH.  The excess data is not stored.

o The carriage return and line feed characters in a TEXT file are not inserted
  in the variables by GET(). Neither is the Control-Z character (if any) that
  indicates end of data. If these characters are present in a BINARY file, they
  are to be inserted into the variables.

o If there is insufficient data before the end of the file to satisfy the
  length on a GET() from a BINARY file, then the last (or only) variable
  contains only the data that was available.

o If a variable is strongly typed and the data cannot be converted to the data
  type of that variable, an error results.


ΓòÉΓòÉΓòÉ 77.6. More about FILE'PUT() ΓòÉΓòÉΓòÉ

o The output file can be divided into separate records using the LINE()
  function or other data items with a data type of FORMAT.

o If an expression is a reference to an array, with index 0, then all the
  elements of the array are concatenated and written to the file as one record.


ΓòÉΓòÉΓòÉ 78. FILEDLG ΓòÉΓòÉΓòÉ

The FILEDLG object class provides access to the standard Presentation Manager
File dialog, which prompts the user to select a file. The dialog uses file
names and extended attributes to determine which files it lists. Here is an
example of the window produced by the File dialog:

Attributes

Actions

Examples

More about FILEDLG


ΓòÉΓòÉΓòÉ 78.1. Attributes ΓòÉΓòÉΓòÉ

BUTTONTITLE              CODE
DIRLISTTXT               DRIVELISTTXT
EA                       FILELISTTXT
FILENAMETXT              FILTERLISTTXT
HELP                     HELPTITLE
IDENTIFIER               LIBNAME
LOCATION                 NAME
TITLE


ΓòÉΓòÉΓòÉ 78.1.1. BUTTONTITLE ΓòÉΓòÉΓòÉ

The text to appear on the push button that confirms the file selection.

Default: "Open"


ΓòÉΓòÉΓòÉ 78.1.2. CODE ΓòÉΓòÉΓòÉ

The most recent error code from the File dialog. For details of the error
codes, see More about FILEDLG. Can be queried but not modified.

Default: 0 (No error)


ΓòÉΓòÉΓòÉ 78.1.3. DIRLISTTXT ΓòÉΓòÉΓòÉ

The text to appear above the list box for the list of directories.

Default: "Directory:"


ΓòÉΓòÉΓòÉ 78.1.4. DRIVELISTTXT ΓòÉΓòÉΓòÉ

The text to appear above the drop-down entry field for the drive identifier.

Default: "Drive:"


ΓòÉΓòÉΓòÉ 78.1.5. EA ΓòÉΓòÉΓòÉ

The default type of extended attribute to be used.

Default: "<All Files>"


ΓòÉΓòÉΓòÉ 78.1.6. FILELISTTXT ΓòÉΓòÉΓòÉ

The text to appear above the list box for the list of file names.

Default: "File:"


ΓòÉΓòÉΓòÉ 78.1.7. FILENAMETXT ΓòÉΓòÉΓòÉ

The text to appear above the single-line entry field for the name of the
selected file.

Default: "Open filename:"


ΓòÉΓòÉΓòÉ 78.1.8. FILTERLISTTXT ΓòÉΓòÉΓòÉ

The text to appear above the drop-down entry field for the list of extended
attributes.

Default: "Type of file:"


ΓòÉΓòÉΓòÉ 78.1.9. HELP ΓòÉΓòÉΓòÉ

The resource identifier (res ID) of the help text for the dialog.

Default: None


ΓòÉΓòÉΓòÉ 78.1.10. HELPTITLE ΓòÉΓòÉΓòÉ

The text to appear in the title bar of the help window.

Default: None


ΓòÉΓòÉΓòÉ 78.1.11. IDENTIFIER ΓòÉΓòÉΓòÉ

The fully qualified name of the selected file. Can be set on open but not
modified.

Default: None


ΓòÉΓòÉΓòÉ 78.1.12. LIBNAME ΓòÉΓòÉΓòÉ

The fully qualified name of the file that contains the help text (.HLP file).
The file must be in a directory in the path defined by the HELP environment
variable in the CONFIG.SYS file.

Default: None


ΓòÉΓòÉΓòÉ 78.1.13. LOCATION ΓòÉΓòÉΓòÉ

Location (the OS/2 path) that the File dialog starts from.

Default: The current drive and path


ΓòÉΓòÉΓòÉ 78.1.14. NAME ΓòÉΓòÉΓòÉ

The file specification used to determine which files are displayed in the
dialog. This can contain the wildcard characters  ? and  *.

Default: None


ΓòÉΓòÉΓòÉ 78.1.15. TITLE ΓòÉΓòÉΓòÉ

The text to appear in the title bar of the File dialog window.

Default: None


ΓòÉΓòÉΓòÉ 78.2. Actions ΓòÉΓòÉΓòÉ

EALIST()            OPEN()


ΓòÉΓòÉΓòÉ 78.2.1. EALIST() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇEALIST(ext_attrs)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

The EALIST action provides the data for the list of extended attributes. The
ext_attrs parameter is an array of values for the TYPE extended attribute.


ΓòÉΓòÉΓòÉ 78.2.2. OPEN() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇOPEN()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

The OPEN action displays the File dialog, using the current attributes.


ΓòÉΓòÉΓòÉ 78.3. Examples ΓòÉΓòÉΓòÉ

! In this example, the File dialog shows all files with the extended attribute
! "Bitmap" in the directory C:\OS2\BIN\. The extended attributes list
! contains the text strings in the elements of the MyEaList array, as well
! as the default "<All Files>" choice. The call to the OPEN action occurs in
! an expression, and the result (the selected file) is assigned to a variable.

OPEN FILEDLG MyFileDlg,           ! Open an instance of the FILEDLG
 LOCATION = "C:\OS2\BIN",         ! Set the attributes
 NAME     = "*.*",
 EA       = "Bitmap"

DEFINE MyEaList[3]
LET MyEaList[1] = "Bitmap"
LET MyEaList[2] = "Plain text"
LET MyEaList[3] = "Icon"
CALL MyFileDlg'EALIST(MyEaList)

LET filename = MyFileDlg'OPEN()   ! Display the window and get the result

! Alternatively, the OPEN action could be called, then the
! IDENTIFIER attribute queried to find out which file was selected.

CALL MyFileDlg'OPEN                     ! display the window
LET filename = MyFileDlg'IDENTIFIER     ! get the result

Examples source library:


ΓòÉΓòÉΓòÉ 78.4. More about FILEDLG ΓòÉΓòÉΓòÉ

o There are two ways to find out which file the user selected. One way is to
  use the OPEN action in an expression and assign the result to a variable. The
  other way is to explicitly call the OPEN action and then query the IDENTIFIER
  attribute. Both ways are shown in the examples.

o Error return codes are stored in the CODE attribute. The codes have the
  following meanings:

   Code      Meaning
   3         Attribute not valid.
   6         The application made an action call that is not valid.
   7         The system could not create a PM-aware thread.
   9         The system could not create a semaphore.
   10        An error occurred while waiting for a semaphore.
   17        A directory could not be queried.
   19        The system could not create an instance of the HELP object.
   20        The system could not associate the HELP object.
   22        The system could not display a help message.
   23        The system could not shut the HELP object.
   24        An error occurred when referencing a HELP object.
   25        Parameter or attribute value not valid.


ΓòÉΓòÉΓòÉ 79. FIND() ΓòÉΓòÉΓòÉ

The FIND() function returns the position in a vector at which a specified value
is held.

                    ΓöîΓöÇ1ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ              ΓöîΓöÇ"="ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöÇΓöÇFIND(ref,value,ΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇ,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ,ΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                    ΓööΓöÇfirstΓöÇΓöÿ   ΓööΓöÇlastΓöÇΓöÿ   ΓööΓöÇcompareΓöÇΓöÿ

Examples

More about FIND()

See also: ROW()


ΓòÉΓòÉΓòÉ 79.1. Examples ΓòÉΓòÉΓòÉ

IF FIND(words, newword) = 0
  INSERT words[0] = newword

LET recno = FIND(pf.number, searchnumber, 10, 20, ">=")

Examples source library:


ΓòÉΓòÉΓòÉ 79.2. More about FIND() ΓòÉΓòÉΓòÉ

o FIND() returns the position of the first match, based on the value of
  compare. If compare is  "=" (the default), then FIND() returns the position
  of the first occurrence. If no match is found, then FIND() returns zero.

o first can be used to continue a FIND() operation looking for a further
  occurrence.


ΓòÉΓòÉΓòÉ 80. FOLDER ΓòÉΓòÉΓòÉ

The FOLDER object class provides folders like those provided by the OS/2
Workplace Shell:

Folders can contain items-FOLDERITEM objects. Items can themselves be folders.

Items are positioned in a hierarchy that is represented by a view-a FOLDERVIEW
object.

Attributes

Actions

Events

Examples

See also: FOLDERITEM, FOLDERVIEW,


ΓòÉΓòÉΓòÉ 80.1. Attributes ΓòÉΓòÉΓòÉ

CODE                        DETAILHEADINGTEXT
EDITABLE                    FOLDERITEM
HEADINGTEXT                 NAMEHEADINGTEXT
TYPEHEADINGTEXT


ΓòÉΓòÉΓòÉ 80.1.1. CODE ΓòÉΓòÉΓòÉ

Last return code from the object.


ΓòÉΓòÉΓòÉ 80.1.2. DETAILHEADINGTEXT ΓòÉΓòÉΓòÉ

Title for the detail column when this folder is shown in the details view.

Default: ""


ΓòÉΓòÉΓòÉ 80.1.3. EDITABLE ΓòÉΓòÉΓòÉ

Whether the attributes HEADINGTEXT, NAMEHEADINGTEXT, TYPEHEADINGTEXT, and
DETAILHEADINGTEXT can be edited directly by an end user when an open FOLDERVIEW
object represents this FOLDER object:

0         The attributes can not be edited
1         The attributes can be edited

Default: 0 (Attributes can not be edited)


ΓòÉΓòÉΓòÉ 80.1.4. FOLDERITEM ΓòÉΓòÉΓòÉ

Pointer to the FOLDERITEM object that this FOLDER is associated with.

Default: 0


ΓòÉΓòÉΓòÉ 80.1.5. HEADINGTEXT ΓòÉΓòÉΓòÉ

Displayed in the client area of the window when a FOLDERVIEW object is
associated with this object.

Default: ""


ΓòÉΓòÉΓòÉ 80.1.6. NAMEHEADINGTEXT ΓòÉΓòÉΓòÉ

Title for the name column when this folder is shown in the details view.

Default: ""


ΓòÉΓòÉΓòÉ 80.1.7. TYPEHEADINGTEXT ΓòÉΓòÉΓòÉ

Title for the type column when this folder is shown in the details view.

Default: ""


ΓòÉΓòÉΓòÉ 80.2. Actions ΓòÉΓòÉΓòÉ

QUERYORDER()            SETORDER()
QUERYVIEWS()


ΓòÉΓòÉΓòÉ 80.2.1. QUERYORDER() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇQUERYORDER(ordervec)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Retrieves the order of the FOLDER object's child FOLDERITEM objects. Fills the
vector ordervec with pointers to the FOLDERITEM objects.


ΓòÉΓòÉΓòÉ 80.2.2. SETORDER() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSETORDER(ordervec)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Sets the order of the FOLDER object's child FOLDERITEM objects, using pointers
to the FOLDERITEM objects in the vector ordervec.


ΓòÉΓòÉΓòÉ 80.2.3. QUERYVIEWS() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇQUERYVIEWS(viewvec)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Retrieves the FOLDER object's child FOLDERVIEW objects. Fills the vector
viewvec with pointers to the FOLDERVIEW objects.


ΓòÉΓòÉΓòÉ 80.3. Events ΓòÉΓòÉΓòÉ

DATA             OPEN


ΓòÉΓòÉΓòÉ 80.3.1. DATA ΓòÉΓòÉΓòÉ

Signaled when FOLDER data is edited directly. A.System.Object is a pointer to
the FOLDER object. A.System.Boxnumber is set to the number of the field being
edited:

1         HEADINGTEXT
2         NAMEHEADINGTEXT
3         TYPEHEADINGTEXT
4         DETAILHEADINGTEXT

A.System.Boxvalue is set to the new data.


ΓòÉΓòÉΓòÉ 80.3.2. OPEN ΓòÉΓòÉΓòÉ

Signaled when the FOLDERITEM representing this FOLDER is double clicked, or
when it has cursor focus and the Enter key is pressed.


ΓòÉΓòÉΓòÉ 80.4. Examples ΓòÉΓòÉΓòÉ

PROCEDURE OpenFolders()
!
! This example opens a hierarchy of folder items, some of which are
! themselves folders.  Then it opens two views of the hierarchy.
!
DO
  ! First open the FOLDERITEM that is the root of the hierarchy.
  OPEN FOLDERITEM Root,
    ICON = "Folder.ico"

  ! The root of the hierarchy has to be a folder, so open a FOLDER
  ! object and associate it with the root FOLDERITEM.
  OPEN FOLDER Folder1,
    FOLDERITEM = POINTER("Root")

  ! Now open a FOLDERITEM in folder 1.
  ! The icon associated with CMD.EXE is used for this item.
  OPEN FOLDERITEM Item1, Folder1,
    ICON = "C:\OS2\CMD.EXE",
    NAME = "Item 1"

  ! Open another item in folder 1.  Make the item into a folder
  ! by opening a second folder and associating it with this item,
  ! (in the same way as for the root item and folder 1).
  OPEN FOLDERITEM Item2, Folder1,
    ICON = "Folder.ico",
    NAME = "Folder 2"

  OPEN FOLDER Folder2,
    FOLDERITEM = POINTER("Item2")

  ! Open two more items, this time in folder 2.
  OPEN FOLDERITEM Item3, Folder2,
    ICON = "D:\DSS\FTB.ICO",
    NAME = "Item 3"

  OPEN FOLDERITEM Item4, Folder2,
    ICON = "D:\DSS\TUT.ICO",
    NAME = "Item 4"

  ! Open two views of the hierarchy.  A tree view of folder 1...
  OPEN FOLDERVIEW View1, Folder1,
    WINDOWTITLE = "Folder 1 - Tree view",
    VIEW = "TreeText",
    SIZEX = 300,
    SIZEY = 300,
    TREEVIEWINDENT = 50

  ! ...and a detail view of folder 2.
  OPEN FOLDERVIEW View2, Folder2,
    WINDOWTITLE = "Folder 2 - Detail view",
    VIEW = "Detail",
    SIZEX = 400,
    SIZEY = 200

END

! The EXPAND event is used to expand a folder within a view.
ON EXPAND(pFolder)
DO
  DECLARE POINTER pFolder
  CALL (?A.System.Object)'EXPAND(pFolder)
END

! The CONTRACT event is used to contract a folder within a view.
ON CONTRACT(pFolder)
DO
  DECLARE POINTER pFolder
  CALL (?A.System.Object)'CONTRACT(pFolder)
END

Examples source library:


ΓòÉΓòÉΓòÉ 81. FOLDERITEM ΓòÉΓòÉΓòÉ

The FOLDERITEM object class provides an item in a hierarchy of folder items.

An item might or might not be a folder. If an item is a folder, then open a
FOLDER object that references the FOLDERITEM.

Parent: FOLDER (except when the item is the root of the hierarchy).

Attributes

Actions: None.

Events

Examples

See also: FOLDER, FOLDERVIEW.


ΓòÉΓòÉΓòÉ 81.1. Attributes ΓòÉΓòÉΓòÉ

VISIBLE                 OPENED
ICON                    X
Y                       NAME
TYPE                    DETAIL
EDITABLE                POPUPMENUREF
RESOURCE                HELP
FOLDER                  CODE


ΓòÉΓòÉΓòÉ 81.1.1. VISIBLE ΓòÉΓòÉΓòÉ

Whether the FOLDERITEM object is visible:

0         Invisible
1         Visible

Default: 1 (Visible)


ΓòÉΓòÉΓòÉ 81.1.2. OPENED ΓòÉΓòÉΓòÉ

Whether the FOLDERITEM object is open:

0         Closed
1         Open

Default: 0 (Closed)


ΓòÉΓòÉΓòÉ 81.1.3. ICON ΓòÉΓòÉΓòÉ

The name of the associated icon: either the fully qualified name of an icon
file, or a string in the form  dllname<id>, where dllname is the name of a DLL
and id is the resource ID of the icon within that DLL.

Default: ""


ΓòÉΓòÉΓòÉ 81.1.4. X ΓòÉΓòÉΓòÉ

Horizontal position of the icon in any child FOLDERVIEW object, in pixels. The
system calculates the value of X. It is redundant for a top level FOLDERITEM
object.


ΓòÉΓòÉΓòÉ 81.1.5. Y ΓòÉΓòÉΓòÉ

Vertical position of the icon in any child FOLDERVIEW object, in pixels. The
system calculates the value of Y. It is redundant for a top level FOLDERITEM
object.


ΓòÉΓòÉΓòÉ 81.1.6. NAME ΓòÉΓòÉΓòÉ

The name of the FOLDERITEM object. This is the name displayed in a names view,
or next to the icon in a details view or tree view when this FOLDERITEM object
is represented by a FOLDERVIEW object.

Default: ""


ΓòÉΓòÉΓòÉ 81.1.7. TYPE ΓòÉΓòÉΓòÉ

The type of the FOLDERITEM object. This is the type displayed in a details view
when this FOLDERITEM object is represented by a FOLDERVIEW object.

Default: ""


ΓòÉΓòÉΓòÉ 81.1.8. DETAIL ΓòÉΓòÉΓòÉ

User defined data associated with the FOLDERITEM object. This is displayed in
the details column in a details view when this FOLDERITEM object is represented
by a FOLDERVIEW object.

Default: ""


ΓòÉΓòÉΓòÉ 81.1.9. EDITABLE ΓòÉΓòÉΓòÉ

Whether the attributes NAME, TYPE, and DETAIL can be edited directly by an end
user when an open FOLDERVIEW object represents this FOLDERITEM object:

0         The attributes can not be edited
1         The attributes can be edited

Default: 0 (Attributes can not be edited)


ΓòÉΓòÉΓòÉ 81.1.10. POPUPMENUREF ΓòÉΓòÉΓòÉ

Reference to the pop-up menu. The name of a vector of menuitems in an object
store.

Default: ""


ΓòÉΓòÉΓòÉ 81.1.11. RESOURCE ΓòÉΓòÉΓòÉ

The name of the module containing the help resource for displaying context
sensitive help.

Default: ""


ΓòÉΓòÉΓòÉ 81.1.12. HELP ΓòÉΓòÉΓòÉ

ID for the help panel in the help resource.

Default: 0


ΓòÉΓòÉΓòÉ 81.1.13. FOLDER ΓòÉΓòÉΓòÉ

Pointer to the FOLDER object that this FOLDERITEM is associated with.


ΓòÉΓòÉΓòÉ 81.1.14. CODE ΓòÉΓòÉΓòÉ

Last return code from the object. Possible return codes are listed in the
Return codes section, which follows.


ΓòÉΓòÉΓòÉ 81.2. Events ΓòÉΓòÉΓòÉ

DATA             OPEN

This object can also signal a BREAK event, subject to the usual rules.


ΓòÉΓòÉΓòÉ 81.2.1. DATA ΓòÉΓòÉΓòÉ

Signaled when FOLDERITEM data is edited directly. A.System.Object is set to the
object's name. A.System.Boxnumber is set to the number of the field being
edited:

1         NAME
2         TYPE
3         DETAIL

A.System.Boxvalue is set to the new data.


ΓòÉΓòÉΓòÉ 81.2.2. OPEN ΓòÉΓòÉΓòÉ

Signaled when the FOLDERITEM is double clicked, or when the Enter key is
pressed, and no FOLDER has been associated by using the FOLDER attribute.


ΓòÉΓòÉΓòÉ 81.3. Examples ΓòÉΓòÉΓòÉ

For examples, see FOLDER.

Examples source library:


ΓòÉΓòÉΓòÉ 82. FOLDERVIEW ΓòÉΓòÉΓòÉ

The FOLDERVIEW object class provides a view of a folder on the screen. You can
display more than one view of the same folder by opening more than one
FOLDERVIEW object.

Parent: FOLDER

Attributes

Actions

Events

Examples

See also: FOLDER, FOLDERITEM.


ΓòÉΓòÉΓòÉ 82.1. Attributes ΓòÉΓòÉΓòÉ

WINDOWTITLE                    X
Y                              SIZEX
SIZEY                          VIEW
FGCOLOR                        BGCOLOR
HEADINGVISIBLE                 DETAILHEADINGVISIBLE
NAMEVISIBLE                    TYPEVISIBLE
DETAILVISIBLE                  LINESPACING
TREEVIEWINDENT                 TREELINEVISIBLE
SELECTION                      MENUREF
SOURCECTRL                     TARGETCTRL
TARGETX                        TARGETY


ΓòÉΓòÉΓòÉ 82.1.1. WINDOWTITLE ΓòÉΓòÉΓòÉ

Title for the frame window.

Default: ""


ΓòÉΓòÉΓòÉ 82.1.2. X ΓòÉΓòÉΓòÉ

Horizontal position on the screen in pixels.

Default: Calculated by the system


ΓòÉΓòÉΓòÉ 82.1.3. Y ΓòÉΓòÉΓòÉ

Vertical position on the screen in pixels.

Default: Calculated by the system


ΓòÉΓòÉΓòÉ 82.1.4. SIZEX ΓòÉΓòÉΓòÉ

Horizontal size in pixels.

Default: Calculated by the system


ΓòÉΓòÉΓòÉ 82.1.5. SIZEY ΓòÉΓòÉΓòÉ

Vertical size in pixels.

Default: Calculated by the system


ΓòÉΓòÉΓòÉ 82.1.6. VIEW ΓòÉΓòÉΓòÉ

Type of view. One of:

"DETAIL"
"FLOWEDNAME"
"FLOWEDTEXT"
"ICON"
"NAME"
"TEXT"
"TREENAME"
"TREETEXT"

Default: "ICON"


ΓòÉΓòÉΓòÉ 82.1.7. FGCOLOR ΓòÉΓòÉΓòÉ

Foreground color. A color value in the range 0-19.

Default: System default


ΓòÉΓòÉΓòÉ 82.1.8. BGCOLOR ΓòÉΓòÉΓòÉ

Background color. A color value in the range 0-19.

Default: System default


ΓòÉΓòÉΓòÉ 82.1.9. HEADINGVISIBLE ΓòÉΓòÉΓòÉ

Whether the HEADINGTEXT of the associated FOLDER object is visible in the
details view:

0         Invisible
1         Visible

Default: 0 (Invisible)


ΓòÉΓòÉΓòÉ 82.1.10. DETAILHEADINGVISIBLE ΓòÉΓòÉΓòÉ

Whether the NAMEHEADINGTEXT, TYPEHEADINGTEXT, and DETAILHEADINGTEXT of the
associated FOLDER object are visible in the details view:

0         Invisible
1         Visible

Default: 0 (Invisible)


ΓòÉΓòÉΓòÉ 82.1.11. NAMEVISIBLE ΓòÉΓòÉΓòÉ

Whether the name column in the details view is visible:

0         Invisible
1         Visible

Default: 1 (Visible)


ΓòÉΓòÉΓòÉ 82.1.12. TYPEVISIBLE ΓòÉΓòÉΓòÉ

Whether the type column in the details view is visible:

0         Invisible
1         Visible

Default: 1 (Visible)


ΓòÉΓòÉΓòÉ 82.1.13. DETAILVISIBLE ΓòÉΓòÉΓòÉ

Whether the type column in the details view is visible:

0         Invisible
1         Visible

Default: 1 (Visible)


ΓòÉΓòÉΓòÉ 82.1.14. LINESPACING ΓòÉΓòÉΓòÉ

Vertical line spacing between records in pixels.

Default: Defined by the system


ΓòÉΓòÉΓòÉ 82.1.15. TREEVIEWINDENT ΓòÉΓòÉΓòÉ

The distance that a child FOLDERITEM is indented from its parent in a tree
view.

Default: Defined by the system


ΓòÉΓòÉΓòÉ 82.1.16. TREELINEVISIBLE ΓòÉΓòÉΓòÉ

Whether the tree line is visible in a tree view.

0         Invisible
1         Visible

Default: 1 (Visible)


ΓòÉΓòÉΓòÉ 82.1.17. SELECTION ΓòÉΓòÉΓòÉ

The selection type allowed within the FOLDERVIEW:

"SINGLE"
"MULTIPLE"
"EXTENDED"

Default: "SINGLE"


ΓòÉΓòÉΓòÉ 82.1.18. MENUREF ΓòÉΓòÉΓòÉ

The menu reference for the action bar. The name of a vector of menu items in an
object store.

Default: No menu


ΓòÉΓòÉΓòÉ 82.1.19. SOURCECTRL ΓòÉΓòÉΓòÉ

Pointer to a SOURCECTRL object.

Default: No SOURCECTRL object


ΓòÉΓòÉΓòÉ 82.1.20. TARGETCTRL ΓòÉΓòÉΓòÉ

Pointer to a TARGETCTRL object.

Default: No TARGETCTRL object


ΓòÉΓòÉΓòÉ 82.1.21. TARGETX ΓòÉΓòÉΓòÉ

Horizontal position of a drop within the FOLDERVIEW object, in pixels.


ΓòÉΓòÉΓòÉ 82.1.22. TARGETY ΓòÉΓòÉΓòÉ

Vertical position of a drop within the FOLDERVIEW object, in pixels.


ΓòÉΓòÉΓòÉ 82.2. Actions ΓòÉΓòÉΓòÉ

EXPAND()                   CONTRACT()
QUERYSELECTED()            SETSELECTED()


ΓòÉΓòÉΓòÉ 82.2.1. EXPAND() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇEXPAND(fldrptr)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Expands a branch of the tree in a tree view. fldrptr is a pointer to the FOLDER
object that is the node on the tree to be expanded.


ΓòÉΓòÉΓòÉ 82.2.2. CONTRACT() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇEXPAND(fldrptr)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Contracts a branch of the tree in a tree view. fldrptr is a pointer to the
FOLDER object that is the node on the tree to be contracted.


ΓòÉΓòÉΓòÉ 82.2.3. QUERYSELECTED() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇQUERYSELECTED(selvec)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Retrieves the FOLDERITEM object pointers for the objects that are currently
selected in the FOLDERVIEW. Fills the vector selvec with the object pointers.


ΓòÉΓòÉΓòÉ 82.2.4. SETSELECTED() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSETSELECTED(selvec)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Selects FOLDERITEM objects in the FOLDERVIEW. The vector selvec contains object
pointers to the FOLDERITEM objects.


ΓòÉΓòÉΓòÉ 82.3. Events ΓòÉΓòÉΓòÉ

DESKTOP             QUIT
ESCAPE              EXPAND
CONTRACT


ΓòÉΓòÉΓòÉ 82.3.1. DESKTOP ΓòÉΓòÉΓòÉ

Signaled when a desktop event occurs. A.System.Object is set to point to the
FOLDERVIEW object. A.System.Operation is set to one of: "MIN", "MAX", "SIZE",
"NORM", or "MOVE".


ΓòÉΓòÉΓòÉ 82.3.2. QUIT ΓòÉΓòÉΓòÉ

Signaled when Quit is selected from the system menu. A.System.Object is set to
point to the FOLDERVIEW object.


ΓòÉΓòÉΓòÉ 82.3.3. ESCAPE ΓòÉΓòÉΓòÉ

Signaled when the Escape key is pressed and the FOLDERVIEW object has keyboard
focus. A.System.Object is set to point to the FOLDERVIEW object.


ΓòÉΓòÉΓòÉ 82.3.4. EXPAND ΓòÉΓòÉΓòÉ

Signaled when the expand (+) symbol on a folder is selected. A.System.Object is
set to point to the FOLDERVIEW object. A pointer to the folder object being
expanded is passed as a parameter to the event.


ΓòÉΓòÉΓòÉ 82.3.5. CONTRACT ΓòÉΓòÉΓòÉ

Signaled when the contract (-) symbol on a folder is selected. A.System.Object
is set to point to the FOLDERVIEW object. A pointer to the folder object being
expanded is passed as a parameter to the event.


ΓòÉΓòÉΓòÉ 82.4. Examples ΓòÉΓòÉΓòÉ

For examples, see FOLDER.

Examples source library:


ΓòÉΓòÉΓòÉ 83. FORGIVE ΓòÉΓòÉΓòÉ

The FORGIVE statement introduces a statement or block of statements whose
execution does not invoke the ON ERROR block if an error occurs.

ΓöÇΓöÇFORGIVEΓöÇΓöÇstatementlistΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Examples

More about FORGIVE

See also: ON ERROR, FAIL


ΓòÉΓòÉΓòÉ 83.1. Examples ΓòÉΓòÉΓòÉ

FORGIVE x = SQRT(Val)
IF A.System.ErrorNumber \= 0
  ERROR 2, "Unable to find the square root of _.", Val

FORGIVE
  OPEN MMFILE MyMovie,
   NAME     = 'Macaw.AVI',
   LOCATION = 'C:\MMOS2\MOVIES'
IF A.System.ErrorNumber \= 0
THEN DO
  IF MyMovie'CODE \= 0
  THEN ERROR 3, "Couldn't open video file: _", MyMovie'REASON
  ELSE FAIL A.System.ErrorNumber, A.System.ErrorInfo
END

Examples source library:


ΓòÉΓòÉΓòÉ 83.2. More about FORGIVE ΓòÉΓòÉΓòÉ

o The system variables which contain information about any error which can have
  occurred are set as usual. A.System.ErrorNumber is set to 0 at the start of
  the block (that is, whether an error occurs or not), and can be tested after
  FORGIVE to see whether an error has occurred.

o A single statement controlled by FORGIVE, or the DO of a DO...END, can be
  placed on the same line as the FORGIVE statement or on the following line.

o FORGIVE before a CALL will stop error reporting on all statements within the
  called procedure or object action.

o FORGIVE before START PROGRAM does not stop error reporting because START
  PROGRAM starts its own task for executing the program.


ΓòÉΓòÉΓòÉ 84. FULLPATH() ΓòÉΓòÉΓòÉ

The FULLPATH() function returns the fully qualified OS/2 name from a location
name and a file name.

ΓöÇΓöÇFULLPATH(location,filename)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Examples

See also: LOCATION(), NAME()


ΓòÉΓòÉΓòÉ 84.1. Examples ΓòÉΓòÉΓòÉ

LET FullName = FULLPATH("C:\DSS\SAMPLES\ENU", "CHARTEMP")

Examples source library:


ΓòÉΓòÉΓòÉ 85. GATHER ΓòÉΓòÉΓòÉ

The GATHER statement is used to find the unique values in a vector.

GATHER optionally gives the number of times each unique value occurs in the
vector, and the order in which these unique values were found. Values are
accumulated in ascending order.

GATHER can also return the maximum, minimum, and total of values in the
specified quantity array.

ΓöÇΓöÇGATHERΓöÇΓöÇuniqueΓöÇΓöÇ,ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇ,ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇ,ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇ,ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇ,ΓöÇΓöÇΓöÇΓöÇΓöÇ
                       ΓööΓöÇposΓöÇΓöÿ     ΓööΓöÇcountΓöÇΓöÿ     ΓööΓöÇsumΓöÇΓöÿ     ΓööΓöÇmaxΓöÇΓöÿ
ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇ=ΓöÇΓöÇvectorinΓöÇΓöÇ,ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
   ΓööΓöÇminΓöÇΓöÿ                  ΓööΓöÇquantityΓöÇΓöÿ

Examples

More about GATHER

See also: ANALYZE


ΓòÉΓòÉΓòÉ 85.1. Examples ΓòÉΓòÉΓòÉ

Assume you are using the following vectors:

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéInput   ΓöéValues  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöéa       Γöé2       Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöéc       Γöé5       Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöéc       Γöé2       Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöéa       Γöé6       Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöéb       Γöé1       Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöéc       Γöé2       Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöéd       Γöé"NULL"  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöée       Γöé"NULL"  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöée       Γöé4       Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

The statement:

GATHER Uni,, Count = Input

gives the vectors:

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéUni     ΓöéCount   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöéa       Γöé2       Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöéb       Γöé1       Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöéc       Γöé3       Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöéd       Γöé1       Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöée       Γöé2       Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

gives the vectors:

This statement:

GATHER Uni, Order,, Tot, Min, Max = Input, Values

will give the vectors:

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéUni     ΓöéOrder   ΓöéTot     ΓöéMin     ΓöéMax     Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöéa       Γöé1       Γöé8       Γöé2       Γöé6       Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöéb       Γöé5       Γöé1       Γöé1       Γöé1       Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöéc       Γöé2       Γöé9       Γöé2       Γöé5       Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöéd       Γöé7       ΓöéNULL    ΓöéNULL    ΓöéNULL    Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöée       Γöé8       Γöé4       Γöé4       Γöé4       Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

Examples source library:


ΓòÉΓòÉΓòÉ 85.2. More about GATHER ΓòÉΓòÉΓòÉ

o unique values are listed in ascending order.

o unique, total, order, minimum, count, and maximum need not have been defined
  before. If they have been defined before, they are redefined to the correct
  size.

o A NULL value in vectorin causes a NULL entry in the unique array with
  corresponding entries in the other arrays.

o Any elements in vectorin which have corresponding NULL values in quantity are
  not included in count. Therefore, if all values in vectorin associated with a
  single value in unique are NULL, count will contain 0 for this value.

o For minimum and maximum, the data type of the first value in vectorin for
  each element in unique is the data type to which the other values must
  conform. If any of the other values is of a different data type from this
  value, it is ignored if it cannot be converted.

o GATHER is sometimes appropriate as a means of establishing values before
  issuing an ANALYZE statement.


ΓòÉΓòÉΓòÉ 86. GLOBAL() ΓòÉΓòÉΓòÉ

The GLOBAL() function provides the value of a global value which is shared
between applications.

ΓöÇΓöÇGLOBAL(name,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                 ΓööΓöÇnewvalueΓöÇΓöÿ

Examples

More about GLOBAL()

See also: EXTRACTGLOBAL(), REPLACEGLOBAL()


ΓòÉΓòÉΓòÉ 86.1. Examples ΓòÉΓòÉΓòÉ

LET result = GLOBAL("Month", "Jan")             ! result is NULL, probably
LET result = GLOBAL("Month", "Apr")             ! result is "Jan"
LET result = GLOBAL("Month")                    ! result is "Apr"

Examples source library:


ΓòÉΓòÉΓòÉ 86.2. More about GLOBAL() ΓòÉΓòÉΓòÉ

o GLOBAL values are shared between all applications in one session.

o GLOBAL values can be set on the command line:

    FTBAS3 -@Month=Jan@Week=4


ΓòÉΓòÉΓòÉ 87. GRAPHIC ΓòÉΓòÉΓòÉ

The GRAPHIC object class provides a graphic area in a window.

Parent: WINDOW

Attributes

Actions

Events

Examples

More about GRAPHIC

See also: DEFINE object, Standard graphics attributes.

Also see the DDEGS.PRG program in Development Samples.


ΓòÉΓòÉΓòÉ 87.1. Attributes ΓòÉΓòÉΓòÉ

ASPECTRATIO            BGCOLOR
DRAGABLE               HANDLES
HELP                   ORIGIN
EXPRESSION             FGCOLOR
HEIGHT                 PATTERN
SELECTABLE             SIZEX
SIZEY                  SKIPREFRESH
VISIBLE                WCSMINX
WCSMAXX                WCSMINY
WCSMAXY                WIDTH
X                      Y
ZORDER


ΓòÉΓòÉΓòÉ 87.1.1. ASPECTRATIO ΓòÉΓòÉΓòÉ

Whether the aspect ratio of the graphic area is maintained. If the aspect ratio
is ignored, the graphic area is adapted to fill the display space available.

0         Aspect ratio ignored
1         Aspect ratio maintained

Default: 0 (Ignored)


ΓòÉΓòÉΓòÉ 87.1.2. BGCOLOR ΓòÉΓòÉΓòÉ

Background color. Integer in the range 1-19. See Colors and color codes for
details of colors available.

Default: Color used in the window


ΓòÉΓòÉΓòÉ 87.1.3. DRAGABLE ΓòÉΓòÉΓòÉ

Whether objects in the graphic area can be dragged:

0         Objects cannot be dragged
1         Objects can be dragged

Default: 0 (Cannot be dragged)


ΓòÉΓòÉΓòÉ 87.1.4. HANDLES ΓòÉΓòÉΓòÉ

Whether sizing handles are attached to the graphic to support moving, sizing,
and copying operations. These direct manipulation techniques follow the CUA
guidelines. See also the AUTOSELECT attribute of the WINDOW object.

0         Handles are not displayed
1         Handles are displayed

Default: 0 (No handles)


ΓòÉΓòÉΓòÉ 87.1.5. HELP ΓòÉΓòÉΓòÉ

Resource identifier (res ID) number of the full help text for this area.

Default: 0


ΓòÉΓòÉΓòÉ 87.1.6. ORIGIN ΓòÉΓòÉΓòÉ

The corner of the enclosing window to be taken as the origin. The position of
the graphic area is measured from this point.

"TL"      Top left
"TR"      Top right
"BL"      Bottom left
"BR"      Bottom right

Default: "BL" (Bottom left)


ΓòÉΓòÉΓòÉ 87.1.7. EXPRESSION ΓòÉΓòÉΓòÉ

Vector reference containing the file name of a previously saved graphics file.

Default: ""


ΓòÉΓòÉΓòÉ 87.1.8. FGCOLOR ΓòÉΓòÉΓòÉ

Foreground color. Integer in the range 1-19. See Colors and color codes for
details of colors available.

Default: Color used in the window.


ΓòÉΓòÉΓòÉ 87.1.9. HEIGHT ΓòÉΓòÉΓòÉ

Vertical size of the graphic area, in millimeters.

Read-only: Calculated by Presentation Manager


ΓòÉΓòÉΓòÉ 87.1.10. PATTERN ΓòÉΓòÉΓòÉ

Pattern for the graphic area. Integer in the range 0-15. See
Patterns and patterncodes for details of patterns available.

Default: 0


ΓòÉΓòÉΓòÉ 87.1.11. SELECTABLE ΓòÉΓòÉΓòÉ

Whether the graphic area is selectable or not:

0         Graphic area not selectable
1         Graphic area selectable.  Displayed in bold outline.
2         Graphic area selectable.  Displayed in a surrounding box.

Default: 1 (Selectable)


ΓòÉΓòÉΓòÉ 87.1.12. SIZEX ΓòÉΓòÉΓòÉ

Horizontal size of the graphic area, in dialog box units.

Default: 0


ΓòÉΓòÉΓòÉ 87.1.13. SIZEY ΓòÉΓòÉΓòÉ

Vertical size of the graphic area, in dialog box units.

Default: 0


ΓòÉΓòÉΓòÉ 87.1.14. SKIPREFRESH ΓòÉΓòÉΓòÉ

The graphic area is not refreshed automatically.

Default: 0 (Refreshing is done)


ΓòÉΓòÉΓòÉ 87.1.15. VISIBLE ΓòÉΓòÉΓòÉ

Whether the graphic area is displayed:

0         Graphic area not displayed
1         Graphic area displayed

Default: 1 (Displayed)


ΓòÉΓòÉΓòÉ 87.1.16. WCSMINX ΓòÉΓòÉΓòÉ

World coordinate minimum value in the X direction.

Difference between WCSMINX and WCSMAXX must not exceed 32000.

Default: 0


ΓòÉΓòÉΓòÉ 87.1.17. WCSMAXX ΓòÉΓòÉΓòÉ

World coordinate maximum value in the X direction.

Difference between WCSMINX and WCSMAXX must not exceed 32000.

Default: 0


ΓòÉΓòÉΓòÉ 87.1.18. WCSMINY ΓòÉΓòÉΓòÉ

World coordinate minimum value in the Y direction.

Difference between WCSMINY and WCSMAXY must not exceed 32000.

Default: 0


ΓòÉΓòÉΓòÉ 87.1.19. WCSMAXY ΓòÉΓòÉΓòÉ

World coordinate maximum value in the Y direction.

Difference between WCSMINY and WCSMAXY must not exceed 32000.

Default: 0


ΓòÉΓòÉΓòÉ 87.1.20. WIDTH ΓòÉΓòÉΓòÉ

Horizontal size of the graphic area, in millimeters.

Read-only: Calculated by Presentation Manager


ΓòÉΓòÉΓòÉ 87.1.21. X ΓòÉΓòÉΓòÉ

Horizontal position within the window, in dialog box units.

Default: 0


ΓòÉΓòÉΓòÉ 87.1.22. Y ΓòÉΓòÉΓòÉ

Vertical position within the window, in dialog box units.

Default: 0


ΓòÉΓòÉΓòÉ 87.1.23. ZORDER ΓòÉΓòÉΓòÉ

The apparent 3D position of the graphic object on the window.

0         Graphic box is drawn at the same priority as other objects in the
          window
-1        Graphic box is drawn below and is superimposed by any other objects
          in the window.
1         Graphic box is drawn above and superimposes any other objects in the
          window

Default: 0 (Same priority)


ΓòÉΓòÉΓòÉ 87.2. Actions ΓòÉΓòÉΓòÉ

BITMAP()                CLEAR()
CLIPBOARD()             EDIT()
METAFILE()              PRINT()
REFRESH()               SELECT()
STRINGRECT()


ΓòÉΓòÉΓòÉ 87.2.1. BITMAP() ΓòÉΓòÉΓòÉ

                                                   ΓöîΓöÇ"BITMAP"ΓöÇΓöÉ
ΓöÇΓöÇBITMAP(filename,ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇ,ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇ,ΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                      ΓööΓöÇsizexΓöÇΓöÿ     ΓööΓöÇsizeyΓöÇΓöÿ      ΓööΓöÇformatΓöÇΓöÇΓöÇΓöÿ

Saves the screen to a BITMAP sizex is the width in pels. sizey is the height in
pels. format can be:

"BITMAP" (default)
"BITMAP11"
"TIFF"
"PCX"
"GIF"


ΓòÉΓòÉΓòÉ 87.2.2. CLEAR() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇCLEAR()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Clears the graphic window completely.


ΓòÉΓòÉΓòÉ 87.2.3. CLIPBOARD() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇCLIPBOARD()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Saves the current graphic window to the clipboard, in metafile format.


ΓòÉΓòÉΓòÉ 87.2.4. EDIT() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇEDIT(argument)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Enables the programmer to query whether a clipboard operation is supported and,
if it is, to carry it out.

argument is a clipboard query or a clipboard operation.

The following values for argument are used to check whether particular
clipboard operations can be supported with the graphic area in its current
state:

"Querycut" Cut to clipboard
"Querycopy" Copy to clipboard
"Querypaste" Paste from clipboard
"Queryclear" Clear clipboard.

Where clipboard operations are supported, the following values for argument
direct them to be carried out:

"Cut"     Cut to clipboard
"Copy"    Copy to clipboard
"Paste"   Paste from clipboard
"Clear"   Clear clipboard.


ΓòÉΓòÉΓòÉ 87.2.5. METAFILE() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇMETAFILE(filename)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Saves the graphic screen to a metafile named filename.


ΓòÉΓòÉΓòÉ 87.2.6. PRINT() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇPRINT(Pt_name,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇ,ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ,ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ,ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ,c_area)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                   ΓööΓöÇsizeX%,sizeY%,posX%,posY%ΓöÇΓöÿ

Prints the graphic screen.

Pt_name   is a handle to a PRINTER object

sizeX%    is the width of the printed image as a percentage of the page width

sizeY%    is the height of the printed image as a percentage of the page height

posX%     is the horizontal position of the printed image in relation to the
          total width (100%) of the page, measured from the left-hand edge.

posY%     is the vertical position of the printed image in relation to the
          total height (100%) of the page, measured from the bottom edge.

c_area    is set to 1 to indicate printing client area only, a value of 0
          results in the window frame printing as well.

Note:   If the  sizeX,sizeY,posX, and posY parameters are left blank, the
        graphic box will be forced to a uniform aspect ratio on the printed
        output.


ΓòÉΓòÉΓòÉ 87.2.7. REFRESH() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇREFRESH()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Refreshes the graphic window and repaints all objects on the current window.


ΓòÉΓòÉΓòÉ 87.2.8. SELECT() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSELECT(vector,n,x,y,x_tolerance,y_tolerance)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

When the graphic area is selected, it is possible to find out if any objects
were selected. This is done by calling Grabox'SELECT, where Grabox is the
handle of the graphic object used in the OPEN GRAPHIC statement. The names of
any objects found are returned into a vector. If no objects are found the
number of entries is set to zero.

Returns in vector a Z-ordered list of objects positioned within the specified
tolerance of the X and Y coordinates. The X and Y coordinates themselves are
retrieved from the system variables A.System.PositionX, and A.System.PositionY.
These variables are in turn set by the SELECT event. n is the maximum number of
objects that the system should report on as found in the specified area of the
screen.


ΓòÉΓòÉΓòÉ 87.2.9. STRINGRECT() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSTRINGRECT(result,string,multiline,alignment,font,ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
ΓöÇΓöÇcellx,celly,0,angle,directionΓöÇΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Returns a vector containing the boundaries for text, (top right-hand corner and
bottom left-hand corner).

STRINGRECT is a call to a graphic box on a window which returns the amount of
space a graphic text string will occupy when displayed in the graphic box. It
is not possible to calculate this area directly because of the nonproportional
font characters.

STRINGRECT can also be used in Charts to calculate the text layout and prevent
text overlap.

The call is passed as parameters: all the attributes associated with the text
STRING along with the name of an array for holding the returned coordinates of
the rectangle enclosing the text.

result    is the vector holding the coordinates of the enclosing rectangle.

string    is the predefined vector holding the string definition and location.
          (The same vector as used by the OPEN STRING statement.)

multiline Method of multiline display

alignment String alignment.

font      Font used for the string characters

cellx     X cell size

celly     Y cell size

0         Place holder for a reserved parameter

angle     Text angle

direction Printing direction.

For values of multiline, alignment, font, cellx, celly, angle, and direction,
see the corresponding attributes of the STRING object.


ΓòÉΓòÉΓòÉ 87.3. Events ΓòÉΓòÉΓòÉ

DESKTOP            DRAG
OPEN               SELECT

The example below shows how to use STRINGRECT to calculate the size of graphic
text.

OPEN WINDOW AppWin
OPEN GRAPHIC GraBox,AppWin
DEFINE TextVect[0]
INSERT TextVect[0] = 500 !  Insert x coordinate into variable.
INSERT TextVect[0] = 400 !  Insert y coordinate into variable.
INSERT TextVect[0] = "my text"
                         !  Insert text into variable.
CALL GraBox'STRINGRECT(
        TextBox,         !  Will hold returned values.
        TextVect,        !  Holds text and position.
        MultiLine,
        Alignment,
        Font,
        XSize,
        YSize,
        0,               !  Reserved.
        Angle,
        Direction)       !  The TextBox vector now contains
                         !  the coordinates of the enclosing
                         !  rectangle.

Graphic text strings can use the MULTILINE attribute to display text in a
graphic box in two different ways, the returned values will depend on how
MULTILINE was used:

o When MULTILINE is set to 1, the system expects the contents of the text array
  (TextVect in the example above) to contain the coordinate values followed by
  one or more lines of text:

   500 - The X coordinate

   400 - The Y coordinate

   "First  Text  Line"

   "Second Text  Line"

   "Third  Text  Line"

   "Fourth Text  Line"

o When MULTILINE is 1, STRINGRECT fills the TextBox array with eight values
  corresponding to the four pairs of x,y coordinates of the corners of the
  surrounding rectangle.

o When MULTILINE is set to 0 then the STRING object can be used to display
  multiple single line strings. In this case the system expects the TextVect
  array to hold one or more triplets of elements consisting of an X coordinate,
  a Y coordinate, and a single text string:

   300 - The X coordinate

   400 - The Y coordinate

   "First line" - Text string of first triplet

   600 - The X coordinate

   800 - The Y coordinate

   "Second line" - Text string of second triplet

In this instance, STRINGRECT fills the TextBox array with elements in multiples
of eight. Each set of eight elements corresponds to the text defined by one of
the triplets in the TextVect array and supplies the x,y coordinates of the
rectangle surrounding the text.


ΓòÉΓòÉΓòÉ 87.3.1. DESKTOP ΓòÉΓòÉΓòÉ

Signaled when the graphic is moved, sized, or copied. A.System.Operation is set
to "MOVE", "SIZE", or "COPY". A.System.Object contains the name of the control.


ΓòÉΓòÉΓòÉ 87.3.2. DRAG ΓòÉΓòÉΓòÉ

Dragging is finished.


ΓòÉΓòÉΓòÉ 87.3.3. OPEN ΓòÉΓòÉΓòÉ

Mouse button 1 is clicked twice.


ΓòÉΓòÉΓòÉ 87.3.4. SELECT ΓòÉΓòÉΓòÉ

Signaled when selection is made. A.System.Object is set to named graphic area
and A.System.PositionX and A.System.PositionY are set to the coordinates of the
point selected.  Coordinates are in world coordinate scale units.


ΓòÉΓòÉΓòÉ 87.4. Examples ΓòÉΓòÉΓòÉ

/*-----------------------------------------------------*/
/* First set up the window that will hold the graphics.*/
/* This will be used to open the graphic box..         */
/*-----------------------------------------------------*/
OPEN WINDOW Win,
 SIZEX     = 102,
 SIZEY     = 102,
 TITLE     = "Simple graphics..."

/*-----------------------------------------------------*/
/* Now open the graphic box using the window as the    */
/* parent. The size and position are all set on Open,  */
/* and can be modified later if needed.                */
/*-----------------------------------------------------*/
OPEN GRAPHIC Gra, Win,
 X = 1, Y = 1,
 SIZEX   = 100, SIZEY = 100,
 BGCOLOR = 5, DRAGABLE = 1,
 WCSMAXX = 500,
 WCSMAXY = 500,
 WCSMINX = 0,
 WCSMINY = 0

/*-----------------------------------------------------*/
/* Finally create a Define to put the primative(s)     */
/* onto the Graphic. Many Primatives can be added to   */
/* a this define. They would then form a single group. */
/* This define will be Dragable, so all primatives on  */
/* it will be dragable.                                */
/*-----------------------------------------------------*/
OPEN DEFINE Def1, Gra,
 DRAGABLE = 1

/*-----------------------------------------------------*/
/* For examples of opening primatives onto this Define */
/* see the examples for the individual Primatives.     */
/*-----------------------------------------------------*/

  !
  ! Open a DEFINE on which to place the
  ! various sample graphic objects.
  !
  OPEN DEFINE Sample1, Sample,
   Dragable = 0
END

Examples source library:


ΓòÉΓòÉΓòÉ 87.5. More about GRAPHIC ΓòÉΓòÉΓòÉ

o GRAPHIC is used to open a graphic box in which to display something:

    OPEN GRAPHIC {box}, {window}, {savedspec}, {attributes...}

o All graphic primitives to be displayed must be part of a containing object,
  which is created using the DEFINE object:

    OPEN DEFINE {definition}, {box}, {attributes...}

  The graphic primitives themselves, such as line or circle, are then attached:

    OPEN LINE {line}, {definition}, {attributes...}

  To build up complex objects, include previously defined objects in a
  composite object:

    OPEN DEFINE {bigdefine}, {box}, {attributes...}
    OPEN OBJECT {object}, {bigdefine},
                  DEFINE = {definition}, {attributes...}

  The graphic can now be handled as a whole, or each primitive part can be
  handled separately.

  To summarize, each primitive has a parent defined for the parent box. The
  parent box in turn has a parent window.

o The GRAPHIC object cannot be cloned.


ΓòÉΓòÉΓòÉ 88. GROUP ΓòÉΓòÉΓòÉ

The GROUP object class creates an instance of a frame, with or without a title.

Parent: WINDOW

Attributes

Actions

Events

Examples

More about GROUP


ΓòÉΓòÉΓòÉ 88.1. Attributes ΓòÉΓòÉΓòÉ

EXPRESSION            HANDLES
HELP                  ORIGIN
SIZEX                 SIZEY
TEXT                  VISIBLE
X                     Y


ΓòÉΓòÉΓòÉ 88.1.1. EXPRESSION ΓòÉΓòÉΓòÉ

Pointer to a variable, the contents of which are displayed with the frame.

Note that the TEXT and EXPRESSION attributes are mutually exclusive.

Default: ""


ΓòÉΓòÉΓòÉ 88.1.2. HANDLES ΓòÉΓòÉΓòÉ

Whether sizing handles are attached to the group box to support moving, sizing,
and copying operations. These direct manipulation techniques follow the CUA
guidelines. See also the AUTOSELECT attribute of the WINDOW object.

0         Handles are not displayed
1         Handles are displayed

Default: 0 (No handles)


ΓòÉΓòÉΓòÉ 88.1.3. HELP ΓòÉΓòÉΓòÉ

Resource identifier (res ID) number of the full help text for this object.

Default: 0


ΓòÉΓòÉΓòÉ 88.1.4. ORIGIN ΓòÉΓòÉΓòÉ

The corner of the enclosing window to be taken as the origin.  The position of
the bottom left corner of the object is measured from this point.

"TL"      Top left
"TR"      Top right
"BL"      Bottom left
"BR"      Bottom right

Default: "BL" (Bottom left)

Note:   If the vertical position is above the origin, the value is positive. If
        the vertical position is below the origin, the value is negative. If
        the horizontal position is right of the origin, the value is positive.
        If the horizontal position is left of the origin, the value is
        negative.


ΓòÉΓòÉΓòÉ 88.1.5. SIZEX ΓòÉΓòÉΓòÉ

Width, in dialog box units.

Default: 0


ΓòÉΓòÉΓòÉ 88.1.6. SIZEY ΓòÉΓòÉΓòÉ

Height, in dialog box units.

Default: 0


ΓòÉΓòÉΓòÉ 88.1.7. TEXT ΓòÉΓòÉΓòÉ

Text string to appear as title in the frame of the group box.

Note that the TEXT and EXPRESSION attributes are mutually exclusive.

Default: ""


ΓòÉΓòÉΓòÉ 88.1.8. VISIBLE ΓòÉΓòÉΓòÉ

Whether the object is displayed:

0         Object not displayed
1         Object displayed

Default: 1 (Displayed)


ΓòÉΓòÉΓòÉ 88.1.9. X ΓòÉΓòÉΓòÉ

Horizontal position within the window, in dialog box units.

Default: 0


ΓòÉΓòÉΓòÉ 88.1.10. Y ΓòÉΓòÉΓòÉ

Vertical position within the window, in dialog box units.

Default: 0


ΓòÉΓòÉΓòÉ 88.2. Actions ΓòÉΓòÉΓòÉ

EDIT()               REFRESH()


ΓòÉΓòÉΓòÉ 88.2.1. EDIT() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇEDIT(argument)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Enables the programmer to query whether a clipboard operation is supported and,
if it is, to carry it out.

argument is a clipboard query or a clipboard operation.

The following values for argument are used to check whether particular
clipboard operations can be supported with the group box in its current state:

"Querycut" Cut to clipboard
"Querycopy" Copy to clipboard
"Querypaste" Paste from clipboard
"Queryclear" Clear clipboard.

Where clipboard operations are supported, the following values for argument
direct them to be carried out:

"Cut"     Cut to clipboard
"Copy"    Copy to clipboard
"Paste"   Paste from clipboard
"Clear"   Clear clipboard.


ΓòÉΓòÉΓòÉ 88.2.2. REFRESH() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇREFRESH()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Forces repainting of the group object on screen.


ΓòÉΓòÉΓòÉ 88.3. Events ΓòÉΓòÉΓòÉ

DESKTOP


ΓòÉΓòÉΓòÉ 88.3.1. DESKTOP ΓòÉΓòÉΓòÉ

Signaled when the group box is moved, sized, or copied. A.System.Operation is
set to "MOVE", "SIZE", or "COPY". A.System.Object contains the name of the
control.


ΓòÉΓòÉΓòÉ 88.4. Examples ΓòÉΓòÉΓòÉ

!
! Open a GROUP box on a window
!
PROCEDURE open_group(pWindow)
DO
  DECLARE POINTER pWindow

  OPEN group group1, ?pWindow,
   X = 20,
   Y = 50,
   SIZEX = 150,
   SIZEY = 95,
   TEXT = 'Group control'
END

Examples source library:


ΓòÉΓòÉΓòÉ 88.5. More about GROUP ΓòÉΓòÉΓòÉ

o The GROUP object cannot be cloned.


ΓòÉΓòÉΓòÉ 89. HELP ΓòÉΓòÉΓòÉ

The HELP object allows applications to use the IBM Help Manager Information
Presentation Facility (IPF) to display help information to users.

Attributes

Actions

Events

More about HELP

See also: OS/2 Information Presentation Facility Guide and Reference.


ΓòÉΓòÉΓòÉ 89.1. Attributes ΓòÉΓòÉΓòÉ

HELPFORHELP            HYPERTEXTID
KEYS                   LIBNAME
WINTITLE


ΓòÉΓòÉΓòÉ 89.1.1. HELPFORHELP ΓòÉΓòÉΓòÉ

Panel to display when Using help... is requested on the IPF pull-down

Default: IPF supplies its own default.


ΓòÉΓòÉΓòÉ 89.1.2. HYPERTEXTID ΓòÉΓòÉΓòÉ

Resource identifier (res ID) number of a hypertext field selected by the user.

Can be queried but not modified.

Default: None


ΓòÉΓòÉΓòÉ 89.1.3. KEYS ΓòÉΓòÉΓòÉ

Resource identifier (res ID) number of the Keys help... text.

Default: IPF supplies its own default.


ΓòÉΓòÉΓòÉ 89.1.4. LIBNAME ΓòÉΓòÉΓòÉ

Name of the help text (.HLP) library. The file must be located in a directory
name in the HELP variable defined by CONFIG.SYS.

Default: No default


ΓòÉΓòÉΓòÉ 89.1.5. WINTITLE ΓòÉΓòÉΓòÉ

Title for the help window.

A string.

Default: IPF supplies its own default.


ΓòÉΓòÉΓòÉ 89.2. Actions ΓòÉΓòÉΓòÉ

CONTENTS()            DISMISS()
DISPLAY()             INDEX()


ΓòÉΓòÉΓòÉ 89.2.1. CONTENTS() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇCONTENTS()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Requests that the IPF display the help contents text.


ΓòÉΓòÉΓòÉ 89.2.2. DISMISS() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇDISMISS()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Requests that the IPF remove the help associated with the last active object.


ΓòÉΓòÉΓòÉ 89.2.3. DISPLAY() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇDISPLAY(variable)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Requests that the IPF display the help whose resource identifier (res ID) is
held in variable.


ΓòÉΓòÉΓòÉ 89.2.4. INDEX() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇINDEX()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Requests that the IPF display the help index.


ΓòÉΓòÉΓòÉ 89.3. Events ΓòÉΓòÉΓòÉ

HELP              INFORM


ΓòÉΓòÉΓòÉ 89.3.1. HELP ΓòÉΓòÉΓòÉ

Indicates that the Information Presentation Facility could not find help text
for one of the application windows or boxes.

You can now query system variables and the active object to find out the
context of the help request, then make the help object display help text by
calling the DISPLAY action.


ΓòÉΓòÉΓòÉ 89.3.2. INFORM ΓòÉΓòÉΓòÉ

Indicates that the end user selected a hypertext field marked with the INFORM
tag.

You can now query the HYPERTEXTID attribute to find the res ID of the selected
field, and take suitable action.


ΓòÉΓòÉΓòÉ 89.4. More about HELP ΓòÉΓòÉΓòÉ

o The Information Presentation Facility allows you to build files of help
  texts. Windows and other objects have HELP attributes that contain the res ID
  numbers of associated help texts. The HELP object passes requests to display
  help through to the IPF.

o Help can be displayed for the following items:

   - An application window

   - A specific item in a window, such as a selection choice or an entry field

   - One or more words in a help window (known as hypertext fields).

o An instance of the HELP object must be opened before windows or controls with
  the HELP attribute set (the HELP object can then construct the help tables as
  the other objects are opened).


ΓòÉΓòÉΓòÉ 90. HLLAPI ΓòÉΓòÉΓòÉ

The HLLAPI object allows Visualizer to interact with a host using 3270 terminal
emulation or 5250 workstation features.

Attributes

Actions

Events: None.

More about HLLAPI


ΓòÉΓòÉΓòÉ 90.1. Attributes ΓòÉΓòÉΓòÉ

CODE                    CURSORPOS
WINDOWSTATUS            SESSION


ΓòÉΓòÉΓòÉ 90.1.1. CODE ΓòÉΓòÉΓòÉ

Most recent HLLAPI or internal error code.


ΓòÉΓòÉΓòÉ 90.1.2. CURSORPOS ΓòÉΓòÉΓòÉ

When queried, this attribute performs the HLLAPI QUERY CURSOR LOCATION function
on the connected presentation space. This returns the cursors current
positional value.

When modified, this attribute performs the HLLAPI SET CURSOR function. This
places the cursor at the specified positional value in the connected
presentation space.

Use the CONVERTPOS action to convert positional values to row and column values
and vice versa.


ΓòÉΓòÉΓòÉ 90.1.3. WINDOWSTATUS ΓòÉΓòÉΓòÉ

This attribute performs the HLLAPI PM WINDOW STATUS function.

When queried, the PM window state of the currently connected presentation space
is returned as a string of words consisting of VISIBLE or INVISIBLE, ACTIVATED
or DEACTIVATED, or MINIMISED or MAXIMISED.

When modified, the state of the PM window is changed according to the words
contained in the string.  The string of words may consist of any of the above
words plus any of RESTORE, ZORDER=TOP|BOTTOM, MOVE=xpos,ypos, or
SIZE=xsize,ysize.

Note that there are restrictions on which options may be combined within one
command string. (See IBM Extended Services for OS/2 EHLLAPI Programming
Interface, S04G-1027, for more information.)


ΓòÉΓòÉΓòÉ 90.1.4. SESSION ΓòÉΓòÉΓòÉ

When queried this returns the short session name of the currently connected
presentation space.

When modified, any connected presentation space is disconnected and the
application is connected to the short session name specified.


ΓòÉΓòÉΓòÉ 90.2. Actions ΓòÉΓòÉΓòÉ

CONNECT()                 DISCONNECT()
SESSIONPARMS()            WAIT()
PAUSE()                   RELEASE()
RESERVE()                 STATUS()
SESSIONS()                SYSTEM()
RESETSYSTEM()             COPYOIA()
SEARCHPS()                SEARCHFIELD()
FIELDLENGTH()             FIELDPOS()
FIELDATTR()               CONVERTPOS()
SENDKEY()                 COPYPS()
PSTOSTRING()              STRINGTOPS()
FIELDTOSTR()              STRTOFIELD()
SENDFILE()                RECEIVEFILE()


ΓòÉΓòÉΓòÉ 90.2.1. CONNECT() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇCONNECT(session)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action performs the HLLAPI CONNECT PRESENTATION SPACE function.

This establishes a connection between the application and the specified host
presentation space. session is the single character short name of the session
to be connected.


ΓòÉΓòÉΓòÉ 90.2.2. DISCONNECT() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇDISCONNECT()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action performs the HLLAPI DISCONNECT PRESENTATION SPACE function.

This disconnects the application from the currently connected host presentation
space.


ΓòÉΓòÉΓòÉ 90.2.3. SESSIONPARMS() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSESSIONPARMS(string)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action performs the HLLAPI SET SESSION PARAMETERS function.

This allows you to change certain session options from their default values.
string should contain the desired values of the changed options separated by
commas or blanks. (See IBM Extended Services for OS/2 EHLLAPI Programming
Interface, S04G-1027, for more information.)


ΓòÉΓòÉΓòÉ 90.2.4. WAIT() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇWAIT()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action performs the HLLAPI WAIT function.

This checks the status of the currently connected presentation space and waits
according to the setting of TWAIT, NWAIT or LWAIT session options. These
options may be changed by the SESSIONPARMS action.


ΓòÉΓòÉΓòÉ 90.2.5. PAUSE() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇPAUSE(num)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action performs the HLLAPI PAUSE function.

This will cause a timed pause of num 1/2 seconds.


ΓòÉΓòÉΓòÉ 90.2.6. RELEASE() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇRELEASE()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action performs the HLLAPI RELEASE function.

This function unlocks the currently connected presentation space.


ΓòÉΓòÉΓòÉ 90.2.7. RESERVE() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇRESERVE()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action performs the HLLAPI RESERVE function.

This function locks the currently connected presentation space to block input
from the user.


ΓòÉΓòÉΓòÉ 90.2.8. STATUS() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSTATUS(vector)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action performs the HLLAPI QUERY SESSION STATUS function.

This is used to obtain session specific information for the currently connected
session. On return, vector will contain:

 1. Short name of session.
 2. Long name of session.
 3. Type of session.
 4. Characteristics of session.
 5. Number of rows for session.
 6. Number of columns for session.
 7. Host code page for session.


ΓòÉΓòÉΓòÉ 90.2.9. SESSIONS() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSESSIONS(vector)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action performs the HLLAPI QUERY SESSIONS function.

This is used to obtain information for all configured sessions. On return,
vector will contain the following for each configured session:

 1. Short name of session.
 2. Long name of session.
 3. Type of session.
 4. Size of presentation space.


ΓòÉΓòÉΓòÉ 90.2.10. SYSTEM() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSYSTEM(vector)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action performs the HLLAPI QUERY SYSTEM function.

This is used to obtain system related information. On return, vector will
contain:

 1. HLLAPI version number.
 2. HLLAPI level number.
 3. HLLAPI release date.
 4. LIM version number.
 5. LIM level number.
 6. Hardware base.
 7. Control program type.
 8. Control program sequence number.
 9. Control program version number.
10. PC session name.
11. Extended error code 1.
12. Extended error code 2.
13. Hardware base number.
14. PC country code.
15. PC display type.


ΓòÉΓòÉΓòÉ 90.2.11. RESETSYSTEM() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇRESETSYSTEM()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action performs the HLLAPI RESET SYSTEM function.

This resets the system parameters (set with the SESSIONPARMS action) to the
default state and disconnects from any connected presentation space.


ΓòÉΓòÉΓòÉ 90.2.12. COPYOIA() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇCOPYOIA()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action performs the HLLAPI COPY OIA function.

This returns a string containing the Operator Information Area for the
currently connected presentation space.


ΓòÉΓòÉΓòÉ 90.2.13. SEARCHPS() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSEARCHPS(string,posn)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action performs the HLLAPI SEARCH PRESENTATION SPACE function.

This searches the currently connected presentation space for the string string
starting at position posn. The return value contains the position where string
was found or zero if string was not found.


ΓòÉΓòÉΓòÉ 90.2.14. SEARCHFIELD() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSEARCHFIELD(string,posn)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action performs the HLLAPI SEARCH FIELD function.

This searches the currently connected presentation space for a field containing
the string string, starting at position posn. The return value contains the
position where string was found or zero if string was not found.


ΓòÉΓòÉΓòÉ 90.2.15. FIELDLENGTH() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇFIELDLENGTH(option,posn)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action performs the HLLAPI FIND FIELD LENGTH function.

This finds the length of the specified field in the currently connected
presentation space. option and posn are use to specify the field of interest.

Valid values for option are:

'  ' or 'T ' Current field (the field that the cursor is in)

'N '      Next field, either protected or unprotected.

'P '      Previous field, either protected or unprotected.

'NP'      Next protected field.

'NU'      Next unprotected field.

'PP'      Previous protected field.

'PU'      Previous unprotected field.

The return value contains the length of the field or zero if the field was not
found.


ΓòÉΓòÉΓòÉ 90.2.16. FIELDPOS() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇFIELDPOS(option,posn)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action performs the HLLAPI FIND FIELD POSITION function.

This finds the start position of the specified field in the currently connected
presentation space. option and posn are use to specify the field of interest.

Valid values for option are:

'  ' or 'T ' Current field (the field that the cursor is in)

'N '      Next field, either protected or unprotected.

'P '      Previous field, either protected or unprotected.

'NP'      Next protected field.

'NU'      Next unprotected field.

'PP'      Previous protected field.

'PU'      Previous unprotected field.

The return value contains the start position of the field or zero if the field
was not found.


ΓòÉΓòÉΓòÉ 90.2.17. FIELDATTR() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇFIELDATTR(posn)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action performs the HLLAPI QUERY FIELD ATTRIBUTE function.

This returns the attribute value of the field located at position posn in the
currently connected presentation space.


ΓòÉΓòÉΓòÉ 90.2.18. CONVERTPOS() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇCONVERTPOS(posn,column,row)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action performs the HLLAPI CONVERT POSITION function.

This will convert the positional value posn to column/row values or vice versa
for the currently connected presentation space. If posn is nonzero, it is
converted to column/row values returned in column and row. If posn is zero,
column/row values contained in column and row are converted to a positional
value returned in posn.


ΓòÉΓòÉΓòÉ 90.2.19. SENDKEY() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSENDKEY(string)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action performs the HLLAPI SEND KEY function.

This sends the keys as defined by the contents of string to the currently
connected presentation space.


ΓòÉΓòÉΓòÉ 90.2.20. COPYPS() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇCOPYPS(vector)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action performs the HLLAPI COPY PRESENTATION SPACE function.

This copies the entire contents of the currently connected presentation space,
line by line, into vector.


ΓòÉΓòÉΓòÉ 90.2.21. PSTOSTRING() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇPSTOSTRING(posn,length)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action performs the HLLAPI COPY PRESENTATION SPACE TO STRING function.

This returns the contents of the currently connected presentation space as a
string starting at position posn for length length. Note that the maximum
length of the string returned is 255 characters.


ΓòÉΓòÉΓòÉ 90.2.22. STRINGTOPS() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSTRINGTOPS(string,posn)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action performs the HLLAPI COPY STRING TO PRESENTATION SPACE function.

This copies the string string into the currently connected presentation space
at position posn.


ΓòÉΓòÉΓòÉ 90.2.23. FIELDTOSTR() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇFIELDTOSTR(posn,length)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action performs the HLLAPI COPY FIELD TO STRING function.

This returns the contents of the field starting at position posn for length
length as a string. Note that the maximum length of the string returned is 255
characters.


ΓòÉΓòÉΓòÉ 90.2.24. STRTOFIELD() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSTRTOFIELD(string,posn)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action performs the HLLAPI COPY STRING TO FIELD function.

This copies the string string into the field at position posn.


ΓòÉΓòÉΓòÉ 90.2.25. SENDFILE() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSENDFILE(string)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action performs the HLLAPI SEND FILE function.

This executes the SEND.EXE program as if it had been entered at the command
line. The contents of string must be an acceptable syntax for the send command.
The return value is the return code from the send call.


ΓòÉΓòÉΓòÉ 90.2.26. RECEIVEFILE() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇRECEIVEFILE(string)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action performs the HLLAPI RECEIVE FILE function.

This executes the RECEIVE.EXE program as if it had been entered at the command
line. The contents of string must be an acceptable syntax for the receive
command. The return value is the return code from the receive call.


ΓòÉΓòÉΓòÉ 90.3. More about HLLAPI ΓòÉΓòÉΓòÉ

o See the HLLAPI sample in the Development Samples folder.


ΓòÉΓòÉΓòÉ 91. IBMAPPLICATN ΓòÉΓòÉΓòÉ

The Application object provides a way for one application to start another
application and communicate with it.

Attributes

Actions

Events: None.

Examples

More about


ΓòÉΓòÉΓòÉ 91.1. Attributes ΓòÉΓòÉΓòÉ

CODE                  DIALOG
IDENTIFIER            NAME
REASON


ΓòÉΓòÉΓòÉ 91.1.1. CODE ΓòÉΓòÉΓòÉ

Internal error code for the most recent operation. Read-only.

Default: None


ΓòÉΓòÉΓòÉ 91.1.2. DIALOG ΓòÉΓòÉΓòÉ

Whether dialogs are used for error reporting:

0         Dialogs are suppressed
1         A dialog is activated to handle the error condition.


ΓòÉΓòÉΓòÉ 91.1.3. IDENTIFIER ΓòÉΓòÉΓòÉ

The complete path and name of the application.


ΓòÉΓòÉΓòÉ 91.1.4. NAME ΓòÉΓòÉΓòÉ

The name of the application. This name is used in messages.


ΓòÉΓòÉΓòÉ 91.1.5. REASON ΓòÉΓòÉΓòÉ

Text message for the most recent error code.


ΓòÉΓòÉΓòÉ 91.2. Actions ΓòÉΓòÉΓòÉ

OPEN()               REFRESH()
SAVETO()             CLOSE()
DISCARD()            ACTION()


ΓòÉΓòÉΓòÉ 91.2.1. OPEN() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇOPEN()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

ΓöÇΓöÇPROCESS()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

ΓöÇΓöÇNEW()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

All these actions start the application if it has not already been started.

Codes returned are:

o 4100 - Application not successfully accessed

o 4101 - Application not successfully started


ΓòÉΓòÉΓòÉ 91.2.2. REFRESH() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇREFRESH()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

The action activates the application's ON QUEUE event block with Refresh as a
parameter. The return code sets the CODE attribute to 0.


ΓòÉΓòÉΓòÉ 91.2.3. SAVETO() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSAVETO(Destination)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

If Destination is valid, a copy of the application is saved to the specified
destination. The action returns various OS/2 error codes in CODE. If the
destination is read-only, the value 4020 is returned.


ΓòÉΓòÉΓòÉ 91.2.4. CLOSE() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇCLOSE()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

The application's STOP block is run. The application can be re-started using
another OPEN action. CODE is set to 0.


ΓòÉΓòÉΓòÉ 91.2.5. DISCARD() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇDISCARD()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Attempts to stop and erase the application (the QUIT block is activated after
erasing the application). The return codes are:

o OS/2 error codes

o 4020 - Application read-only

o 4012 - Discard cancelled

o 4103 - Discard failed


ΓòÉΓòÉΓòÉ 91.2.6. ACTION() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇACTION(parms)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

ACTION() activates the destination application's ON QUEUE event block with
literal string Action and a pointer to the parmsvector as parameters. The
destination application's return code is placed in the CODE attribute when the
event is complete.


ΓòÉΓòÉΓòÉ 91.3. Examples ΓòÉΓòÉΓòÉ

The QUEUE block can pass back up to 9 parameters (see examples below). The
calling application's return code is in A.System.Return.

!  ---- Example 1 ---------
! Application A
ON SELECT
    . . .
  OPEN IBMAPPLICATN AppB,
    NAME = "My little application",
    IDENTIFIER = "D:\MyApp",
    DIALOG = 1
  rc = AppB'OPEN( )
    ! This is essential before calling ACTION
  IF \rc
    rc = AppB'ACTION(parm1,parm2,parm3,...parm10)
    . . .
  CALL AppB'CLOSE( )
   ! Not entirely necessary if we're going to SHUT it.
  SHUT AppB
    . . .

ON QUIT
    . . .
    WHEN "AppB"
      SHUT AppB

ON QUEUE(parm1, .. , parm9)
    ! Process action from app B
    RETURN code

! ------- EXAMPLE 2 -------
!  Application B
ON START
    . . .
    Caller = A.System.Program
   ! Handle for communication with App A
    . . .

ON QUEUE(action, parmsvecptr)
DO
  CASE action
    WHEN "Refresh"
      ! App A called REFRESH action
      ! Interpret refresh action
    WHEN "Action"
      ! App A called ACTION action
    DO
      parm1 = (?parmsvecptr)[1]
      . . .  etc.
      ! Interpret action
      RETURN code
    END
END

ON SELECT
    . . .
  RUN PROGRAM Caller, QUEUE(parm1, .. , parm9)
  rc = A.System.Return
    . . .

Examples source library:


ΓòÉΓòÉΓòÉ 91.4. More about ΓòÉΓòÉΓòÉ

o The ON START block of the key program receives the following three
  parameters:

    1. Any additional command line parameters passed.

    2. The full file identifier of the application objectstore.

    3. The name of the application. This is either the WPS title of the
       application, or the NAME attribute of the IBMAPPLICATN object being
       opened. For example:

    ON START(CmdLineParms,Identifier,Name)


ΓòÉΓòÉΓòÉ 92. IBMCHART ΓòÉΓòÉΓòÉ

The IBMCHART object class provides a Visualizer chart.

Attributes

Actions

Events

Error codes

Examples


ΓòÉΓòÉΓòÉ 92.1. Attributes ΓòÉΓòÉΓòÉ

AUTOREFRESH            CODE
DIALOG                 EUIMODE
IBMDATA                IDENTIFIER
MODIFIED               NAME
PERCENTAGE             PERSPECTIVE
REASON                 ROTATED
SAVEPROMPT             TYPE


ΓòÉΓòÉΓòÉ 92.1.1. AUTOREFRESH ΓòÉΓòÉΓòÉ

This attribute may be set to "Yes" or "No" (1 or 0).

1         The view is refreshed automatically.
0         The composed view of the object is not updated until specifically
          requested, thus improving performance by eliminating unnecessary
          processing.


ΓòÉΓòÉΓòÉ 92.1.2. CODE ΓòÉΓòÉΓòÉ

This is the error code from the last action.


ΓòÉΓòÉΓòÉ 92.1.3. DIALOG ΓòÉΓòÉΓòÉ

This attribute may be set to 1 or 0 ("Yes" or "No") to control error or print
dialogs.

1         A dialog is activated to handle the error condition.
0         Dialogs are suppressed, default action taken.


ΓòÉΓòÉΓòÉ 92.1.4. EUIMODE ΓòÉΓòÉΓòÉ

This attribute may be set to "Full" or "Restricted". When set to "Restricted",
the Select table, Select column, and Import options are permanently disabled.

"Restricted" also disables drag/drop from any object to the chart. The user
can, however, drag the chart to another object or to the printer.


ΓòÉΓòÉΓòÉ 92.1.5. IBMDATA ΓòÉΓòÉΓòÉ

Read-only pointer to the IBMDATA object the chart is using.


ΓòÉΓòÉΓòÉ 92.1.6. IDENTIFIER ΓòÉΓòÉΓòÉ

This attribute must be set to the complete path and name of the specification
to be used as a model for the new chart. The specification could be a template
object or an already existing chart.


ΓòÉΓòÉΓòÉ 92.1.7. MODIFIED ΓòÉΓòÉΓòÉ

This attribute indicates whether the object has been modified since it was last
saved.

1         Object has been modified.
0         Object has not been modified.


ΓòÉΓòÉΓòÉ 92.1.8. NAME ΓòÉΓòÉΓòÉ

This attribute may be set to the WPS title of the chart object. This name will
then be used as the window title.


ΓòÉΓòÉΓòÉ 92.1.9. PERCENTAGE ΓòÉΓòÉΓòÉ

This attribute may be set to "Off", "X", "Y", or "All".

"Off"     no percentage calculations are made.
"X"       each Y value is calculated as a percentage of all Y values for a
          particular X value.
"Y"       each Y value is calculated as a percentage of all Y values for the
          analysis.
"All"     each Y value is calculated as a percentage of all Y values for all
          analyses.


ΓòÉΓòÉΓòÉ 92.1.10. PERSPECTIVE ΓòÉΓòÉΓòÉ

This attribute may be set to "Yes" or "No" (1 or 0).

1         charts are displayed in 3D.
0         charts are displayed in 2D.


ΓòÉΓòÉΓòÉ 92.1.11. REASON ΓòÉΓòÉΓòÉ

This is the error message sent from the last action.


ΓòÉΓòÉΓòÉ 92.1.12. ROTATED ΓòÉΓòÉΓòÉ

This attribute may be set to "Yes" or "No" (1 or 0).

1         axis based charts are displayed rotated 90┬░ clockwise.
0         axis based charts are not rotated.


ΓòÉΓòÉΓòÉ 92.1.13. SAVEPROMPT ΓòÉΓòÉΓòÉ

This Boolean attribute is to disable the COPY TO menu option.

1         Normal operation
0         Prevents the application from performing a COPY TO.


ΓòÉΓòÉΓòÉ 92.1.14. TYPE ΓòÉΓòÉΓòÉ

This attribute may be set to "Line", "Surface", "Scatter", "Bar", "Pie", or
"Mixed".


ΓòÉΓòÉΓòÉ 92.2. Actions ΓòÉΓòÉΓòÉ

COPYTO()                  DISCARD()
OPEN()                    PRINT()
PROCESS()                 RESET()
RESETDATA()               REFRESHDATA()
SELECTTABLE()             QUERYFORMATS()
SAVE()                    SETAXISTYPE()
SELDATA                   SELANALYSIS()
SEND()                    SETXAXISLAB()
SETYAXISLAB()             SETTITLE()


ΓòÉΓòÉΓòÉ 92.2.1. COPYTO() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇCOPYTO(identifier,format)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Makes a copy of the current object. identifier is the full name and location of
the file into which the chart will be copied. (If the file exists, it will be
overwritten.)

Format controls the data format used:

IBMCHART  native chart format
METAFILE  OS/2 Metafile
BITMAP    OS/2 bitmap (compatible with Windows 3.0 bitmap)
BITMAP11  OS/2 1.1 bitmap
PCX       ZSoft PC Paintbrush Image format
TIFF      A subset of Microsoft and Aldus Tagged Image File Format
GIF       Compuserve Graphics Interchange Format


ΓòÉΓòÉΓòÉ 92.2.2. DISCARD() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇDISCARD()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

The DISCARD action deletes the instance of the object.


ΓòÉΓòÉΓòÉ 92.2.3. OPEN() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇOPEN()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

The OPEN action puts a view of the object on the screen.


ΓòÉΓòÉΓòÉ 92.2.4. PRINT() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇPRINT(ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
           ΓööΓöÇNameΓöÇΓöÿ   ΓööΓöÇPrintDialogΓöÇΓöÿ

The PRINT action generates output suitable for printing or plotting. Name is
the name of the printer to use (the printer name is the device name of a
Workplace Shell printer object) or a pointer to an open printer object. If "*",
the Workplace Shell default printer is assumed. (The default printer is
specified by the OS/2 Print Manager.)

Name, the DIALOG attribute, and the PrintDialog parameter determine whether
panels and messages will be displayed to the user:

If the DIALOG attribute is 0 (false), then no panels are displayed (PrintDialog
is ignored).

If Name is a pointer to a printer and the DIALOG attribute is 1 (true), then
the printer's own dialog is used.

If Name is not a pointer to a printer, and if the DIALOG attribute is 1 (true),
and if PrintDialog is 1 (true), then a dialog is presented to the user.

If Name is blank and there are to be no dialogs, then the Workplace Shell
default printer is used.


ΓòÉΓòÉΓòÉ 92.2.5. PROCESS() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇPROCESS()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

If AUTOREFRESH is off, API calls which change the underlying data are not
immediately reflected in the displayed object (or metafile). PROCESS forces an
update to redraw the chart.


ΓòÉΓòÉΓòÉ 92.2.6. RESET() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇRESET()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action resets all the chart settings back to their default values.


ΓòÉΓòÉΓòÉ 92.2.7. RESETDATA() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇRESETDATA()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action resets the current input table specification. All data items are
reset, including all column selections.


ΓòÉΓòÉΓòÉ 92.2.8. REFRESHDATA() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇREFRESHDATA()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action refreshes the chart to use the latest version of the data. The
action is equivalent to the user selecting Refresh data from the menu bar.


ΓòÉΓòÉΓòÉ 92.2.9. SELECTTABLE() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSELECTTABLE(Table,FilingSystem.)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action specifies a new table to be used as input to the object. Table is
the fully qualified name of the input table, including any environment specific
location information. This form of location information for each environment;

o for OS/2 files it is Drive:\Directory while

o for Database Manager tables it is Database or Database\Userid; for AS400
  tables it is System\Library; for host AS tables it is ASCode.

FilingSystem may be any one of "PRODUCT", "SQL", "AS400", "HOST", "IXF",
"PCIXF", "FLAT", "LIST", "DBF", "DIF".

If the SelectTable( ) action is called when there are no current column
selections, the Select columns window is opened automatically, subject to the
Dialog attribute setting. With Chart you can prevent this dialog opening when
using a template with no column selections as a starting point, by issuing the
API calls to select columns before issuing the SelectTable call. This technique
does not work for Report because Report requires the table to be specified
before columns may be selected.

If you access SQL or DB2 tables via Host AS, then AS issues an ATTACH command
that uses the installation's default database. To override this default or
other AS Attach command parameter defaults, you should issue your own Attach
command when AS is started. This can be placed in a User Profile Table, as
described in Application System: Developing Applications


ΓòÉΓòÉΓòÉ 92.2.10. QUERYFORMATS() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇQUERYFORMATS(pFormats)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action will fill the vector pointed to by pFormats with the data formats
that IBMCHART can render. (See COPYTO() for values for pFormats.)


ΓòÉΓòÉΓòÉ 92.2.11. SAVE() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSAVE()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action saves the object.


ΓòÉΓòÉΓòÉ 92.2.12. SETAXISTYPE() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSETAXISTYPE(Axis,Type)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action specifies the required data type to be plotted against a given
axis. The values for Axis may be "X", "Y", or "Z". The values for Type may be
"Numeric" or "Date" for the Y axis, while the X or Z axes can be "Numeric",
"Date", or "Character". Subsequent columns selected against specific axes must
be of the correct data type.


ΓòÉΓòÉΓòÉ 92.2.13. SELDATA ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSELDATAX(Column)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

ΓöÇΓöÇSELDATAZ(Column)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

These actions specify the columns to be plotted against the X and Z axes. Both
are optional. The X column defaults to the table row number.


ΓòÉΓòÉΓòÉ 92.2.14. SELANALYSIS() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSELANALYSIS(Column,Function,Display)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action specifies an analysis to be plotted against the Y axis. Column is a
column from the current table, a value of 1 will cause a count of unique Y
values for each X point to be used. Function may be "Tot", "Min", "Max", "Avg",
or "Det". "Det" will display every Y data point for each X data point, the
other functions aggregate multiple Y data points into a single Y data point for
each X data point. Display may be "Abs" for absolute, or "Cum" for cumulative.

Up to 25 analyses may be defined. If the same analysis is specified twice, the
second is treated as a deselection of that analysis.


ΓòÉΓòÉΓòÉ 92.2.15. SEND() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSEND(pFormats)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action mails copies of the chart in the specified formats. pFormats points
to a vector of format names. (See COPYTO() for values for pFormats.)


ΓòÉΓòÉΓòÉ 92.2.16. SETXAXISLAB() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSETXAXISLAB(Text)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action specifies text to be used as the X axis label.


ΓòÉΓòÉΓòÉ 92.2.17. SETYAXISLAB() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSETYAXISLAB(Text)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action specifies text to be used as the Y axis label.


ΓòÉΓòÉΓòÉ 92.2.18. SETTITLE() ΓòÉΓòÉΓòÉ

              <ΓöÇ,ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöÇΓöÇSETTITLE(ΓöÇΓöÇΓöÇΓöÇtextΓöÇΓöÇΓö┤ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Defines up to eight lines of the chart object's title.

text      The text to be used for the line of the title. Empty lines in the
          8-line title can be indicated by using two double quotes ( "").


ΓòÉΓòÉΓòÉ 92.3. Events ΓòÉΓòÉΓòÉ

QUIT


ΓòÉΓòÉΓòÉ 92.3.1. QUIT ΓòÉΓòÉΓòÉ

This event is signaled whenever the object handler has been requested by the
user to terminate. Use A.System.Object to identify the object handler in
question, and to issue API calls prior to shutting the object.


ΓòÉΓòÉΓòÉ 92.4. Error codes ΓòÉΓòÉΓòÉ

5067      An incorrect value has been used when setting the Chart Type or
          Percentage attribute. The value is ignored.

5068      An incorrect axis type has been specified on a Chart SetAxisType
          action. The action is ignored.

5069      An incorrect axis has been specified on a Chart SetAxisType action.
          The action is ignored.

5070      A SELDATAX action has been called without previously calling
          SetAxisType for the X axis. The action is ignored.

5071      A SELDATAZ action has been called without previously calling
          SetAxisType for the Z axis. The action is ignored.

5072      A SelAnalysis action has been called without previously calling
          SetAxisType for the Y axis. The action is ignored.

5073      An incorrect function has been specified on a SelAnalysis action. The
          action is ignored.

5074      An incorrect display value has been specified on a SelAnalysis
          action. The action is ignored.

5075      The average function has been specified on a SelAnalysis action when
          the Y axis type is date. The action is ignored.

5076      The average function has been specified on a SelAnalysis action when
          the display is cumulative. The action is ignored.

5077      A column name of 1 (count of unique Y values) has been specified on a
          SelAnalysis action when the Y axis type is not numeric. The action is
          ignored.

5078      A function other than total has been specified on a SelAnalysis
          action when the column name is 1 (count of unique Y values). The
          action is ignored.

5079      The detail function has been specified on a SelAnalysis action when
          the the current chart is 3D, or a pie or bar chart. The action is
          ignored.

5080      The detail function has been specified on a SelAnalysis action when
          the current chart is additive. The action is ignored.

5081      A SelAnalysis action has attempted to exceed the maximum number of
          analyses. The action is ignored.

5524      An application has registered data on the clipboard, but the
          application is now closing.


ΓòÉΓòÉΓòÉ 92.5. Examples ΓòÉΓòÉΓòÉ

This example uses the EMPDATA data table and produces a specific Chart.

o Chart to be produced:

  Bar Chart of average Annual Salary calculated by Division (X-axis) and Sex
  (Z-axis).

PROCEDURE NewChart
DO
  FORGIVE
    OPEN ?"IBMCHART" MyChart,        /* in case CHART not installed      */
     NAME        = "My Chart",
     IDENTIFIER  = "D:\DSS\Chart",
     TYPE        = "BAR",
     AUTOREFRESH = "0"               /* don't refresh the chart yet      */

  IF A.System.ErrorNumber \= 0
  DO
    IF A.System.ErrorNumber = 2810
    THEN ERROR 1, "Sorry, Visualizer Charts must be installed to continue"
    ELSE RUN PROGRAM A.System.ThisTask, ERROR

    RETURN
  END

  CALL MyChart'RESETDATA()           /* clear any existing data table    */

  !
  ! The next set of calls establishes the X, Z, and Y data.
  ! They are called before the input table is defined, to
  ! prevent the Select Columns dialog appearing automatically.
  !
  ! The axis type for each axis has to be set. The Chart uses this
  ! information to verify that the input data are of the correct type.
  !
  CALL MyChart'SETAXISTYPE('X', 'CHARACTER')
  CALL MyChart'SELDATAX('Division')

  CALL MyChart'SETAXISTYPE('Z', 'NUMERIC')
  CALL MyChart'SELDATAZ('JobCode')

  CALL MyChart'SETAXISTYPE('Y', 'NUMERIC')
  CALL MyChart'SelAnalysis(          /* The Y column is specified by a   */
                                     /* function and display method      */
                                     /* to form an Analysis.             */
    'AnnualSalary',                  /* Column is AnnualSalary.          */
    'Avg',                           /* Show the average                 */
    'Abs')                           /* Absolute (not cumulative) values */

  !
  ! Now, select a data table into the chart
  !
  CALL MyChart'SelectTable("D:\DSS\EMPDATA","PRODUCT")

  !
  ! All done: show the chart
  !
  CALL MyChart'OPEN()
  LET MyChart'AUTOREFRESH = 1   /* any further changes apply immediately */
END

Examples source library:


ΓòÉΓòÉΓòÉ 93. IBMDATA ΓòÉΓòÉΓòÉ

The IBMDATA object (together with the VIEWORDER, VIEWCALCS and VIEWROWS
objects) allows sophisticated table manipulation.

Attributes

Actions

Events: None.

Examples

More about IBMDATA

See also: VIEWCALCS, VIEWORDER, VIEWROWS, VIEWTABLES


ΓòÉΓòÉΓòÉ 93.1. Attributes ΓòÉΓòÉΓòÉ

CODE                    DIALOG
FILINGSYSTEM            MODIFIED
PATH                    REASON
TABLE


ΓòÉΓòÉΓòÉ 93.1.1. CODE ΓòÉΓòÉΓòÉ

Internal error code for the most recent operation. Read-only.

Default: None


ΓòÉΓòÉΓòÉ 93.1.2. DIALOG ΓòÉΓòÉΓòÉ

This specifies whether error messages should be issued directly to the screen.

Default: 1 (Messages issued)


ΓòÉΓòÉΓòÉ 93.1.3. FILINGSYSTEM ΓòÉΓòÉΓòÉ

The filing system where the source data can be found. This also covers file
types:

"PRODUCT" A Visualizer table or query
"SQL"     An SQL data file, including those accessed using DDCS/2
"AS400"   An AS/400 file accessed using PC Support.
"HOST"    A host AS file.
"IXF"     Supported OS/2 filetype
"PCIXF"   Supported OS/2 filetype
"FLAT"    Supported OS/2 filetype
"LIST"    Supported OS/2 filetype
"DBF"     Supported OS/2 filetype
"DIF"     Supported OS/2 filetype

Default: "PRODUCT" (See IBMTABLE for more details on file types.)


ΓòÉΓòÉΓòÉ 93.1.4. MODIFIED ΓòÉΓòÉΓòÉ

A flag to say if the data definition has been modified since the last SAVE( )
or LOAD( ) action. Read-only.

Default: 0 (Not modified)


ΓòÉΓòÉΓòÉ 93.1.5. PATH ΓòÉΓòÉΓòÉ

The route to the source data:

TABLE, QUERY, or OS/2 file "drive:\directory"

SQL table "database", or  "database\userid" (including tables accessed using
          DDCS/2)

AS/400 table Either  "system/library/file" (with TABLE set to member), or
          "system/library" (with TABLE set to file).

Host AS table "ASCode"


ΓòÉΓòÉΓòÉ 93.1.6. REASON ΓòÉΓòÉΓòÉ

Text message of most recent error code. Read-only.

Default: None


ΓòÉΓòÉΓòÉ 93.1.7. TABLE ΓòÉΓòÉΓòÉ

The name of the data table to use. This may be a table in the wider sense, for
example, it may be a query, or on the Host.

Default: ""


ΓòÉΓòÉΓòÉ 93.2. Actions ΓòÉΓòÉΓòÉ

COLUMNS()                   INFO()
INQCALCS()                  INQCOLPROP()
INQCOLUMNS()                INQGROUPBY()
INQINFO()                   INQKEYS()
INQROWS()                   INQSUMMARYCALCS()
INQTYPES()                  LOAD()
PRODUCTCOLUMNS()            QUERYFORMATS()
REFRESHDATA()               SAVE()
SETCALCS()                  SETCOLPROP()
SETCOLUMNS()                SETGROUPBY()
SETROWS()                   SETSUMMARYCALCS()
SNAPSHOT()                  USETMPSOURCE()


ΓòÉΓòÉΓòÉ 93.2.1. COLUMNS() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇCOLUMNS(pointer)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

pointer identifies a vector in which the names of the candidate columns of the
data are returned (in the original form of the column names, as they are in the
external database).


ΓòÉΓòÉΓòÉ 93.2.2. INFO() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇINFO(pointer)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

pointer identifies a vector to be filled with startup parameters for a database
accessed through host AS. The example code below sets typical start-up
information. However, most database installations do not run with the defaults
but have specific parameters for start up.

! This call passes host specific information to the IBMDATA object.
! Note: to use a default value specify "****"

DEFINE HostInfo[0]
INSERT HostInfo[0] = ""          ! Initial command (used for attach)
INSERT HostInfo[0] = "****"      ! Code page to use
INSERT HostInfo[0] = "DASSERV"   ! Server name
INSERT HostInfo[0] = "PRODUCT"   ! Code used to start AS
INSERT HostInfo[0] = "****"      ! Autologon command file

CALL MyData'INFO(POINTER(Info[0]))


ΓòÉΓòÉΓòÉ 93.2.3. INQCALCS() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇINQCALCS(pointer)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

pointer identifies a vector to be filled with the current calculate columns
expressions.


ΓòÉΓòÉΓòÉ 93.2.4. INQCOLPROP() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇINQCOLPROP(Column_name,Property,Pointer)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

pointer identifies a variable to contain the property for the calculated column
specified by column_name. Property can be "TYPE", "FORMAT", or "WIDTH".


ΓòÉΓòÉΓòÉ 93.2.5. INQCOLUMNS() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇINQCOLUMNS(pointer)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

pointer identifies a vector to be filled with the current selected columns.


ΓòÉΓòÉΓòÉ 93.2.6. INQGROUPBY() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇINQGROUPBY(columns,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                        ΓööΓöÇdirectionΓöÇΓöÿ

INQGROUPBY() queries the grouping column names. It is only valid when
FILINGSYSTEM is "SQL".

columns   Pointer to a vector that will be filled with the grouping column
          names.

direction Optional pointer to a vector to be filled with either "ASC" for
          ascending, or "DESC" for descending.


ΓòÉΓòÉΓòÉ 93.2.7. INQINFO() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇINQINFO(pointer)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Identifies a vector to be filled with the host AS startup parameters specified
using the Info action.  This action is used to query the startup parameters
(the startup parameters cannot be modified by this action).


ΓòÉΓòÉΓòÉ 93.2.8. INQKEYS() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇINQKEYS(pointer)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

pointer identifies a vector to be filled with the Visualizer names of the key
columns of the data.


ΓòÉΓòÉΓòÉ 93.2.9. INQROWS() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇINQROWS(Pointer)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

pointer identifies a vector to be filled with the current select rows
expressions.


ΓòÉΓòÉΓòÉ 93.2.10. INQSUMMARYCALCS() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇINQSUMMARYCALCS(expressions)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

INQSUMMARYCALCS() queries the summary calculated column expressions. It is only
valid when FILINGSYSTEM is "SQL".

expressions Pointer to a vector that will be filled with the summary
          expressions.


ΓòÉΓòÉΓòÉ 93.2.11. INQTYPES() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇINQTYPES(pointer)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

pointer identifies a vector to be filled with the column types of the data. The
possible types are NUMERIC, DATE, TIME, CHARACTER, and GRAPHIC.


ΓòÉΓòÉΓòÉ 93.2.12. LOAD() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇLOAD(pointer,element)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

pointer identifies a vector containing a new data definition to be used. The
data definition starts at element element. The new data definition completely
replaces the old one. The vector must contain a specification that was
previously generated by a SAVE( ) action.


ΓòÉΓòÉΓòÉ 93.2.13. PRODUCTCOLUMNS() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇPRODUCTCOLUMNS(pointer)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

pointer identifies a vector in which Visualizer candidate column names of the
data are returned. (The Visualizer column name length is limited to 20
characters).


ΓòÉΓòÉΓòÉ 93.2.14. QUERYFORMATS() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇQUERYFORMATS(ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                  ΓööΓöÇpFormatsΓöÇΓöÿ   ΓööΓöÇpExtensionsΓöÇΓöÿ

QueryFormats allows applications to find out what data formats the IBMDATA
object supports and what the default file extensions are for each format.  The
parameters are defined as follows:

pFormats  A pointer to a vector into which the list of formats supported by the
          IBMDATA Object is placed.
pExtensions A pointer to a vector into which the list of default extensions
          corresponding to the supported data formats is placed.

The values currently returned by the IBMDATA object are listed below (these may
change in the future).

Format    Extension
IBMTABLE
IBMQUERY
IBMSQLSTATEMENT
SQL
AS400
HOST
IXF       IXF
PCIXF     PCI
FLAT      FLT
LIST      LST
DBF       DBF
DIF       DIF

If either parameter is omitted, then QueryFormats returns the information
associated with the other parameter.


ΓòÉΓòÉΓòÉ 93.2.15. REFRESHDATA() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇREFRESHDATA()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Refreshdata is used to take a new look at the source data. For performance
reasons, any action that the DATA object takes is stored and used again. For
example, once a SNAPSHOT has been performed, further calls to SNAPSHOT will
return the same temporary table name (except for actions like SETROWS or
SETCALCS which perform an automatic refresh). If a new look at the data is
required, the REFRESHDATA action must be used.

Before calling REFRESHDATA you should SHUT any table objects that are using the
previous SNAPSHOT table. This will allow the temporary table to be deleted for
you.


ΓòÉΓòÉΓòÉ 93.2.16. SAVE() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSAVE(pointer)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

pointer identifies a vector to which the current data definition will be
appended.


ΓòÉΓòÉΓòÉ 93.2.17. SETCALCS() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSETCALCS(pointer)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

pointer identifies a vector containing the new calculate columns expressions.
The expressions must be in the correct syntax for the filing system:

o For SQL systems, use SQL syntax and the original column names.
o For AS/400 systems, use Visualizer syntax and column names.
o For host AS, use host syntax with the original column names.
o Other filing systems should use Visualizer syntax and column names.


ΓòÉΓòÉΓòÉ 93.2.18. SETCOLPROP() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSETCOLPROP(Column_name,Property,Value)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This allows you to update a property of a calculated column. Property can be
"TYPE", "FORMAT", or "WIDTH" (quotes must be used around the value).


ΓòÉΓòÉΓòÉ 93.2.19. SETCOLUMNS() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSETCOLUMNS(pointer)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

pointer identifies a vector containing the new selected columns (uses the
Visualizer 20-character maximum length form of column names).


ΓòÉΓòÉΓòÉ 93.2.20. SETGROUPBY() ΓòÉΓòÉΓòÉ

                        ΓöîΓöÇ"ASC"ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöÇΓöÇSETGROUPBY(columns,ΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                        ΓööΓöÇdirectionΓöÇΓöÿ

SETGROUPBY() specifies grouping columns. It is only valid when FILINGSYSTEM is
"SQL".

columns   Pointer to a vector of column names to group by. The vector must not
          contain calculated column names or expressions.

direction Optional pointer to a vector containing either "ASC" for ascending,
          or "DESC" for descending.

          Default: "ASC"

To clear the grouping columns, use an empty columns vector.


ΓòÉΓòÉΓòÉ 93.2.21. SETROWS() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSETROWS(Pointer)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

pointer identifies a vector containing the new select rows expressions to be
used. These replace the old select rows expressions. The new expressions must
be in the correct syntax for the filing system.

o For SQL systems, use SQL syntax and the original column names.

o For AS/400 systems, use AS/400 syntax and original column names. (AS/400
  expressions are in Visualizer syntax for calculated columns and in AS/400
  syntax for select rows.)

o For host AS, use host syntax with the original column names.

o Other filing systems should use Visualizer syntax and column names.

A maximum of ten SetRows statements can be used with one IBMDATA object.


ΓòÉΓòÉΓòÉ 93.2.22. SETSUMMARYCALCS() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSETSUMMARYCALCS(expressions)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

SETSUMMARYCALCS() specifies summary calculated column expressions. It is only
valid when FILINGSYSTEM is "SQL".

expressions Pointer to a vector that contains the summary expressions. Each
          summary expression is a condition-for example, SalColumn =
          MIN(AnnualSalary).

You can specify a column name that is already used elsewhere. For example, if
you use the expression  AnnualSalary = SUM(AnnualSalary), then the resulting
table contains an AnnualSalary column that is the sum of the real column.

Select summary calculated columns for output in the same way as other columns,
by using the SETCOLUMNS() action. If more than one column exists with the same
name, then the summary calculated column takes precedence when selected using
SETCOLUMNS().

You can base summary calculations on calculated columns, but not on other
summary columns.


ΓòÉΓòÉΓòÉ 93.2.23. SNAPSHOT() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSNAPSHOT(pointer,SnapshotRows)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Snapshot will cause the data definition to be resolved to a temporary table.
Any data extractions will be performed first. pointer identities a scalar for
the name of the temporary table.

SnapshotRows is the number of rows to be returned. An asterisk in quotation
marks ("*") returns all rows.

The CODE attribute should be checked after using Snapshot.


ΓòÉΓòÉΓòÉ 93.2.24. USETMPSOURCE() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇUSETMPSOURCE(TableName,Path,FilingSystem))ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

UseTmpSource allows applications to use a temporary source of data without
losing the previous data definition or affecting the PATH and TABLE settings of
the IBMDATA object. The parameters are defined as follows:

TableName Name of an existing temporary data source.

Path      Route to the temporary data source.

FilingSystem Filing system where the data is stored, or the file type used.
          Refer to the FILINGSYSTEM attribute of the IBMDATA object for details
          of valid values.

The parameters are not stored in the data definition when a SAVE action is
performed.

Once a USETMPSOURCE action has been called, the IBMDATA object uses the
temporary data source if any information needs to be retrieved. The
UseTmpSource settings are reset to NULL if:

o A subsequent UseTmpSource action with NULL parameters is called.

o Any of the TABLE, PATH or FILINGSYSTEM attributes of the IBMDATA object are
  modified.

o A Load action of the IBMDATA object is performed. (This results in a new data
  definition.)
If the UseTmpSource settings are reset (for any of the above reasons) and
actions have been performed since the temporary source was specified,
information subsequently requested is retrieved from the most recently saved
version of the table specified by the IBMDATA object TABLE, PATH and
FILINGSYSTEM attributes.

After using UseTmpSource, the temporary table specified needs to be SHUT before
an IBMDATA object SNAPSHOT action is performed. This allows the temporary table
to be deleted automatically and the original data to be refreshed.


ΓòÉΓòÉΓòÉ 93.3. Examples ΓòÉΓòÉΓòÉ

OPEN IBMDATA MyData,              /* Open the data object,  */
 FILINGSYSTEM = "Host",           /* pointing at a Host     */
 PATH         = "Name",           /* table in AScode Name.  */
 TABLE        = "***demo/staff"

! Make a local Visualizer copy of the data,
! getting all data rows.
!
CALL MyData'SNAPSHOT(POINTER(LocalCopy[0]), '*')

IF MyData'CODE = 0                /* If it worked...        */
THEN DO
  !
  ! Now open the Visualizer table for my own use
  ! in order to get shared access to the data columns in it
  !
  OPEN TABLE MyTab,
   NAME     = NAME(LocalCopy),
   LOCATION = LOCATION(LocalCopy)
END


ΓòÉΓòÉΓòÉ 93.3.1. Example of inquiring on column attributes ΓòÉΓòÉΓòÉ

The column attributes of external name, Visualizer name and type all follow a
similar syntax.  A vector is filled with an entry for each column.

The key column information is different. The call INQKEYS( ) returns a vector
containing only the names of the key columns, with the most significant key as
the first element.

! Get external column names
CALL MyData'COLUMNS(POINTER(ColumnsList[0]))

! Get a list of Visualizer column names from the data.
CALL MyData'PRODUCTCOLUMNS(POINTER(VisTabCols[0]))

DO i = 1 : ColumnsList[0]'ENTRIES
  ERROR 1, "Column _ will map to column _ in a Visualizer table",
   ColumnsList[i], VisTabCols[i]
END


ΓòÉΓòÉΓòÉ 93.3.2. Example of saving the definition in a specification ΓòÉΓòÉΓòÉ

When a file specification for an application is saved, the IBMDATA object
should be called to embed its file specification within the application's file
specification. The IBMDATA specification is not of a fixed length, so if the
applications uses a tag and count method, it will need to determine the number
of elements before and after the addition of the data specification, and set
count accordingly.

PROCEDURE SaveSpecification()
DO
  DEFINE SaveVec[0]
  INSERT SaveVec[0] = "some piece of fixed information"
  INSERT SaveVec[0] = 0   /* the IBMDATA specification start position */
  INSERT SaveVec[0] = "some other piece of fixed information"

  ...
  ! Save something...
  ...

  ! Get MyData to save its specification
  LET SaveVec[2] = 1 + SaveVec[0]'ENTRIES
  CALL MyData'SAVE(POINTER(SaveVec[0]))

  ...
  ! Save something else...
  ...
END

Applications usually open the data object in their ON START block. They use the
LOAD() action at a later time, when they load a spec file.

ON START
DO
  ...
  OPEN IBMDATA MyData      /* Open IBMDATA object to make it   */
  ...                      /* available later.                 */
END

PROCEDURE ReadSpecification(pSpecVec)
DO
  DECLARE POINTER pSpecVec

  DECLARE NUMERIC StartPos = pSpecVec[2]

  ...
  CALL MyData'LOAD(pSpecVec, StartPos)
  ...
END

Examples source library:


ΓòÉΓòÉΓòÉ 93.4. More about IBMDATA ΓòÉΓòÉΓòÉ

o The Select Rows window (from the VIEWROWS object) and the Calculate Columns
  window (from the VIEWCALCS object) assist in table handling by allowing the
  programmer to provide an interface to the end user for specifying calculated
  columns and multiple row selection criteria. The input from the windows is
  verified and entered into the appropriate field of the IBMDATA object.

o Visualizer will sometimes copy an entire row from the host to local memory
  for manipulation, even though only a few of the columns will be used for the
  final table. Ensure that there is sufficient storage to handle the entire row
  when down loading tables from a host connection.

o You can produce SQL statements that perform data aggregation at the server
  end, so that you do not need to use the ASL GATHER function. This may improve
  performance with SQL databases.

  For example, to plot a chart Annual Salary by Division and Sex, you might use
  the following SQL:

    SELECT Division,Sex,SUM(AnnualSalary)
      FROM USERID.EMPDATA
      GROUP BY Division,Sex

  To do this, use the SETGROUPBY() action to generate the GROUP BY statement,
  and use the SETSUMMARYCALCS() action to specify which columns need functions
  to be applied. to them.


ΓòÉΓòÉΓòÉ 94. IBMREPORT ΓòÉΓòÉΓòÉ

IBMREPORT provides an instance of a Visualizer report.

Attributes

Actions

Events

Return codes

Examples


ΓòÉΓòÉΓòÉ 94.1. Attributes ΓòÉΓòÉΓòÉ

AUTOREFRESH            CODE
DIALOG                 EUIMODE
IDENTIFIER             MODIFIED
NAME                   REASON
SAVEPROMPT


ΓòÉΓòÉΓòÉ 94.1.1. AUTOREFRESH ΓòÉΓòÉΓòÉ

This attribute may be set to 1 or 0 ("Yes" or "No").

1         The view is refreshed automatically.
0         The composed view of the object is not updated until specifically
          requested, thus improving performance by eliminating unnecessary
          processing.


ΓòÉΓòÉΓòÉ 94.1.2. CODE ΓòÉΓòÉΓòÉ

This attribute may be queried to obtain the return code of the last operation.
Possible codes are listed below.


ΓòÉΓòÉΓòÉ 94.1.3. DIALOG ΓòÉΓòÉΓòÉ

This attribute may be set to 1 or 0 ("Yes" or "No") to control error dialogs.

1         A dialog is activated to handle the error condition.
0         Dialogs are suppressed, default action taken.


ΓòÉΓòÉΓòÉ 94.1.4. EUIMODE ΓòÉΓòÉΓòÉ

This attribute may be set to "Full" or "Restricted". When set to "Restricted",
the Select table, Select column, Import and Export options are permanently
disabled.

"Restricted" also disables drag/drop from any object (such as table data, link,
paste or paste link) to the report. The user can, however, drag the report to
another object or to the printer.


ΓòÉΓòÉΓòÉ 94.1.5. IDENTIFIER ΓòÉΓòÉΓòÉ

This attribute must be set to the complete path and name of the specification
to be used as a model. The specification could be a template object or an
already existing report.


ΓòÉΓòÉΓòÉ 94.1.6. MODIFIED ΓòÉΓòÉΓòÉ

This attribute indicates whether the object has been modified since it was last
saved.

1         Object has been modified.
0         Object has not been modified.


ΓòÉΓòÉΓòÉ 94.1.7. NAME ΓòÉΓòÉΓòÉ

This attribute can be set to an arbitrary name for the report which will be
used in window titles and print queues.


ΓòÉΓòÉΓòÉ 94.1.8. REASON ΓòÉΓòÉΓòÉ

This attribute contains a textual description of the last error (or "" if no
error has occurred).


ΓòÉΓòÉΓòÉ 94.1.9. SAVEPROMPT ΓòÉΓòÉΓòÉ

This Boolean attribute is to control prompt on save.

1         Normal operation of prompting and saving.
0         Prevents the application from prompting the user to save when
          closing. It also permanently disables the Save and Save as menu
          options.


ΓòÉΓòÉΓòÉ 94.2. Actions ΓòÉΓòÉΓòÉ

SELECTTABLE()             DISCARD()
OPEN()                    PAGESETUP()
PRINT()                   PROCESS()
REFRESHDATA()             SAVE()
COPYTO()                  SAVETO()
SETCOLFORMAT()            SETTOPTITLE()
SELCOLS()                 SETCOLTITLE()
SETCOLWIDTH()             SELANALYSIS()
SEND()


ΓòÉΓòÉΓòÉ 94.2.1. SELECTTABLE() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSELECTTABLE(Table,FilingSystem)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action specifies a new table to be used as input to the object. Table is
the fully qualified name of the input table, including any environment specific
location information:

OS/2 files                          drive:\directory
Database Manager tables             database or database\userid
AS400 tables                        system\library
Host AS tables                      AScode

FilingSystem may be any one of "PRODUCT", "SQL", "AS400", "HOST", "IXF",
"PCIXF", "FLAT", "LIST", "DBF", "DIF".

If the SelectTable() action is called when there are no current column
selections, the Select columns window is opened automatically, subject to the
DIALOG attribute setting. With Chart you can prevent this dialog opening when
using a template with no column selections as a starting point, by issuing the
API calls to select columns before issuing the SELECTTABLE() call. This
technique does not work for Report because Report requires the table to be
specified before columns can be selected.

If you are accessing SQL or DB2 tables via host AS, AS will issue an Attach
command which uses the installation's default database. To override this
default or other AS Attach command parameter defaults, you should issue your
own Attach command when AS is started. This can be placed in a User Profile
Table, as described in Application System: Developing Applications


ΓòÉΓòÉΓòÉ 94.2.2. DISCARD() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇDISCARD()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

The DISCARD action deletes the instance of the object class.


ΓòÉΓòÉΓòÉ 94.2.3. OPEN() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇOPEN()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

The OPEN action puts a view of the object on the screen.


ΓòÉΓòÉΓòÉ 94.2.4. PAGESETUP() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇPAGESETUP(ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇ,ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇ,ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇ,ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
               ΓööΓöÇpapersizeΓöÇΓöÿ      ΓööΓöÇorientationΓöÇΓöÿ     ΓööΓöÇunitΓöÇΓöÿ
ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇ,ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇ,ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇ,ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇ,ΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
   ΓööΓöÇleftΓöÇΓöÿ     ΓööΓöÇrightΓöÇΓöÿ     ΓööΓöÇtopΓöÇΓöÿ     ΓööΓöÇbottomΓöÇΓöÿ      ΓööΓöÇscaleΓöÇΓöÿ

papersize One of:

   "U"       User-defined. (The same size as the report window.)
   "A0"      841 mm x 1189 mm
   "A1"      594 mm x 841 mm
   "A2"      420 mm x 594 mm
   "A3"      297 mm x 420 mm
   "B4"      257 mm x 364 mm
   "LG"      Legal:  8╨╗ in x 14 in
   "FO"      Folio:  8╨╗ in x 13 in
   "A4"      210 mm x 297 mm
   "LT"      Letter:  8╨╗ in x 11 in
   "EX"      Executive:  7╨╝ in x 10╨╗ in
   "B5"      182 mm x 257 mm
   "C5"      162 mm x 229 mm
   "A5"      148 mm x 210 mm
   "DL"      110 mm x 220 mm
   "A6"      105 mm x 148 mm
   "A7"      74 mm x 105 mm
   "A8"      52 mm x 74 mm
   "A9"      37 mm x 52 mm

orientation Page orientation (not used for paper size "U"):

   0         Portrait
   1         Landscape

unit      Margin units:

   0         Millimeters
   1         Inches

left      Width of left margin

right     Width of right margin

top       Depth of top margin

bottom    Depth of bottom margin

scale     Percentage scale for text, in the range 20 - 500.


ΓòÉΓòÉΓòÉ 94.2.5. PRINT() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇPRINT(ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
           ΓööΓöÇprinterΓöÇΓöÿ   ΓööΓöÇdialogΓöÇΓöÿ

The PRINT action generates output suitable for printing or plotting. printer is
an optional parameter indicating the printer to use. If specified, the value
must be one of:

o "*" to indicate the default WPS printer
o The name of a WPS printer
o A pointer to a printer object opened in the calling program.

dialog is an optional parameter indicating how to handle dialogs. If specified,
the value must be one of:

o 1 to surface print dialogs. The dialogs will determine what to print, which
  printer (if not already specified in printer), how many copies to print, and
  what font to use.

o 0 to inhibit dialogs. (Default values will be used for all settings.)

If the printer name has not been specified and the object was opened with the
DIALOG attribute set to 1 (the default), then a standard screen dialog is
invoked which presents the end user with a list of the available printers to
select from.

If the printer name has not been specified and the object was opened with the
DIALOG attribute set to 0, then the default printer is used. If dialog is not
specified, dialogs are surfaced if the DIALOG attribute is set to 1 and Review
print options on the Profile notebook is set. The default printer is specified
by the OS/2 Print Manager.


ΓòÉΓòÉΓòÉ 94.2.6. PROCESS() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇPROCESS()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

PROCESS() forces an update to redisplay the report. If AUTOREFRESH is off, and
you change the underlying data, then use PROCESS() to reflect the changes in
the displayed object or metafile.


ΓòÉΓòÉΓòÉ 94.2.7. REFRESHDATA() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇREFRESHDATA()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action refreshes the report to use the latest version of the data. The
action is equivalent to the user selecting Refresh data from the menu bar.


ΓòÉΓòÉΓòÉ 94.2.8. SAVE() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSAVE()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action saves the object.


ΓòÉΓòÉΓòÉ 94.2.9. COPYTO() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇCOPYTO(filename,format)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

The current data is copied to the fully-qualified file specified in filename.
format can be one of the following:

o "IBMREPORT" a Visualizer report (default)
o "IBMREPORTSUBSET" a Visualizer table containing subtotal values
o "TEXT" an OS/2 file

If successful, 0 will be returned, otherwise an error code will be returned.


ΓòÉΓòÉΓòÉ 94.2.10. SAVETO() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSAVETO(identifier)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

The SAVETO action saves the object to the indicated object, the full path and
name must be supplied as a parameter (for example, c:\DSS\myobj).


ΓòÉΓòÉΓòÉ 94.2.11. SETCOLFORMAT() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSETCOLFORMAT(column,format)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
Long column name ASL format string


ΓòÉΓòÉΓòÉ 94.2.12. SETTOPTITLE() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSETTOPTITLEΓöÇΓöÇ(ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                    ΓööΓöÇline,textΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÿ
                                ΓööΓöÇ,alignΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÿ
                                         ΓööΓöÇ,elementΓöÇΓöÿ

Defines a line of the report object's title. line is the number of the line
within the title. If line is a negative number, the text is inserted before the
existing text.

text is the text to be used for the defined line of the title.

align is the position of text alignment:

"L"       Left align
"R"       Right align
"C"       Center text

element is the number of the text element to be replaced with the new text.

If SETTOPTITLE() is called with no parameters, the existing title is deleted.


ΓòÉΓòÉΓòÉ 94.2.13. SELCOLS() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSELCOLS(Entry)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action selects or deselects columns in a report. The SELECTABLE action
must be called before columns can be selected.

Entry is a pointer to a vector of column names.

For Host tables, long column names should be supplied. For each entry in the
parameter list there is a toggling effect equivalent to selecting the checkbox
in the EUI, (if the column was not selected before this action it is added)
otherwise it is deleted in the report. For multiple instances of the same
column in a call, only one will be dealt with.


ΓòÉΓòÉΓòÉ 94.2.14. SETCOLTITLE() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSETCOLTITLE(Column,Title)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action sets the title (heading) associated with the selected column
Column, to the string Title.


ΓòÉΓòÉΓòÉ 94.2.15. SETCOLWIDTH() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSETCOLWIDTH(Column,Width)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action sets the report display width of selected column Column, to the
value Width.


ΓòÉΓòÉΓòÉ 94.2.16. SELANALYSIS() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSELANALYSIS(Column,A_type,Type,Base)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action toggles analysis for the selected column Column. If the specified
analysis is already displayed, then it is removed, otherwise it is added. The
analysis is determined from the other 3 parameters:

o A_type is the Analysis type and must be one letter from the list below:

   S         Total (the sum of a numeric column)
   C         Count
   H         High
   L         Low
   A         Average (valid for numeric columns only)
   D         Standard deviation (valid for numeric columns only).
   E         Evaluate (calculate the subtotal for a calculated column using the
             same expression as was used to create the calculated column).

o Type = C (Cumulative) or A (Absolute)
o Base is one letter from the list below:

   T         Use total values as the base
   D         Show values as a percentage of Down subtotal
   A         Show values as a percentage of Across subtotal
   G         Show values as a percentage of the grand total.

Note that the similarly named IBMCHART SelAnalysis action has a different
syntax.


ΓòÉΓòÉΓòÉ 94.2.17. SEND() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSEND(pFormats)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action mails copies of the report in the specified formats. pFormats
points to a vector of format names. (See COPYTO() for values for pFormats.)


ΓòÉΓòÉΓòÉ 94.3. Events ΓòÉΓòÉΓòÉ

QUIT


ΓòÉΓòÉΓòÉ 94.3.1. QUIT ΓòÉΓòÉΓòÉ

This event is signaled whenever the object handler has been requested by the
user to terminate. Use A.System.Object to identify the object handler in
question, and to issue API calls prior to shutting the object.


ΓòÉΓòÉΓòÉ 94.3.2. Return codes ΓòÉΓòÉΓòÉ

Objects return error or completion codes to callers as follows:

Code      Meaning
0         Successful completion
1         Unexpected error
2         No parameters defined
3         No table defined
4         Column name not valid
5         Column is controlling across subtotals.


ΓòÉΓòÉΓòÉ 94.4. Examples ΓòÉΓòÉΓòÉ

This example uses the EMPDATA data table to produce the Name, Division and
Annual Salary of people. The title and column width will be adjusted so that
the report shows "Employee Name" instead of "Name" as a column heading.

PROCEDURE open_report
DO
  OPEN IBMREPORT MyReport,
    Name        = "",                   /* Give it a title        */
    Identifier  = "D:\DSS\Report",      /* Use standard template      */
    AutoRefresh = 1,                    /* Switch on refresh            */
    Dialog      = 0                     /* No column selection window   */

  CALL MyReport'SELECTTABLE("D:\DSS\SAMPLES\EMPDATA", 'PRODUCT')
  CALL MyReport'SELCOLS("Name", "Division", "AnnualSalary")

  CALL MyReport'SETCOLTITLE("Name", "Employee Name")
  CALL MyReport'SETCOLWIDTH("Name", 20)

  CALL MyReport'OPEN()                       ! Display the report
END

Examples source library:


ΓòÉΓòÉΓòÉ 95. IBMSQLSTATEMENT ΓòÉΓòÉΓòÉ

The IBMSQLSTATEMENT object class provides a Visualizer SQL Statement object to
store, modify, and run SQL strings.

Attributes

Actions

Events: None.

Examples

See also: IBMSQLTABLE, IBMDATA, DATASESSION, DATATRANS.


ΓòÉΓòÉΓòÉ 95.1. Attributes ΓòÉΓòÉΓòÉ

NAME                  IDENTIFIER
CODE                  MODIFIED
READONLY              DIALOG
CONFIRM               DBNAME


ΓòÉΓòÉΓòÉ 95.1.1. NAME ΓòÉΓòÉΓòÉ

The title of the SQL Statement object.


ΓòÉΓòÉΓòÉ 95.1.2. IDENTIFIER ΓòÉΓòÉΓòÉ

The path, file name, and extension of the specification to be used as a model
for the SQL Statement object.


ΓòÉΓòÉΓòÉ 95.1.3. CODE ΓòÉΓòÉΓòÉ

The error code from the last action.


ΓòÉΓòÉΓòÉ 95.1.4. MODIFIED ΓòÉΓòÉΓòÉ

Whether the object has been modified since it was last saved: either 1
(modified), or 0 (not modified).


ΓòÉΓòÉΓòÉ 95.1.5. READONLY ΓòÉΓòÉΓòÉ

Whether the object is read-only: either 1 (read-only), or 0 (read/write).


ΓòÉΓòÉΓòÉ 95.1.6. DIALOG ΓòÉΓòÉΓòÉ

This attribute may be set to 1 (yes), or 0 (no) to control error or print
dialogs:

1         A dialog is activated to handle the error condition.
0         Dialogs are suppressed, default action taken.


ΓòÉΓòÉΓòÉ 95.1.7. CONFIRM ΓòÉΓòÉΓòÉ

Whether the user must confirm changes: either 1 (changes must be confirmed), or
0 (no confirmation of changes).

Default: 1 (changes must be confirmed)


ΓòÉΓòÉΓòÉ 95.1.8. DBNAME ΓòÉΓòÉΓòÉ

The name of the default database that all subsequent SQL statements will be
sent to.


ΓòÉΓòÉΓòÉ 95.2. Actions ΓòÉΓòÉΓòÉ

OPEN()               SAVE()
REFRESH()            CLOSE()
GETSQL()             PUTSQL()
RUN()


ΓòÉΓòÉΓòÉ 95.2.1. OPEN() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇOPEN()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Puts a view of the object on the screen.


ΓòÉΓòÉΓòÉ 95.2.2. SAVE() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSAVE()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Saves the object


ΓòÉΓòÉΓòÉ 95.2.3. REFRESH() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇREFRESH()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Surfaces the object's primary window and refreshes the contents. Use REFRESH()
after using PUTSQL() to change the contents.


ΓòÉΓòÉΓòÉ 95.2.4. CLOSE() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇCLOSE()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Closes the object, prompting the user to save changes if necessary.


ΓòÉΓòÉΓòÉ 95.2.5. GETSQL() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇGETSQL(string)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Return SQL after substituting variables in string.

Variables are substituted in the same way as in QMF...


ΓòÉΓòÉΓòÉ 95.2.6. PUTSQL() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇPUTSQL(string)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Specify SQL string string.


ΓòÉΓòÉΓòÉ 95.2.7. RUN() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇRUN()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Runs the SQL string, then opens an IBMSQLTABLE view of the resulting data.


ΓòÉΓòÉΓòÉ 95.3. Examples ΓòÉΓòÉΓòÉ

! Opening a saved SQL statement

OPEN IBMSQLSTATEMENT MySQL,
 NAME       = "My saved SQL",
 IDENTIFIER = "d:\ftw\work\mysql"

CALL MySQL'OPEN()

DEFINE NewSQL[0]
INSERT NewSQL[0] = "SELECT Job, SUM(Salary) "
INSERT NewSQL[0] = "FROM Staff "
INSERT NewSQL[0] = "WHERE Dept=@DEPTNUMBER "
INSERT NewSQL[0] = "GROUP BY Job"

LET MySQL'DBNAME = 'SAMPLE'
CALL MySQL'PUTSQL(POINTER(NewSQL[0]))
CALL MySQL'REFRESH()

! Run the new SQL, displaying results in a Data viewer window
CALL MySQL'RUN()

Examples source library:


ΓòÉΓòÉΓòÉ 96. IBMSQLTABLE ΓòÉΓòÉΓòÉ

The IBMSQLTABLE object class provides a Visualizer Data viewer object.

Attributes

Actions

Events: None.

Examples


ΓòÉΓòÉΓòÉ 96.1. Attributes ΓòÉΓòÉΓòÉ

DATABASE             DATATYPE
SQLTABLE             COLNAMES
SQLSTRING            CODE
REASON


ΓòÉΓòÉΓòÉ 96.1.1. DATABASE ΓòÉΓòÉΓòÉ

The database name.


ΓòÉΓòÉΓòÉ 96.1.2. DATATYPE ΓòÉΓòÉΓòÉ

The type of source data. Either of:

"STRING"  SQL string
"TABLE"   Table


ΓòÉΓòÉΓòÉ 96.1.3. SQLTABLE ΓòÉΓòÉΓòÉ

Name of the table in the database (if DATATYPE is set to "TABLE").


ΓòÉΓòÉΓòÉ 96.1.4. COLNAMES ΓòÉΓòÉΓòÉ

Pointer to an array of column names. If you do not specify COLNAMES, then
default column names from the database are used.


ΓòÉΓòÉΓòÉ 96.1.5. SQLSTRING ΓòÉΓòÉΓòÉ

Pointer to an array containing the SQL string (if DATATYPE is set to "STRING").


ΓòÉΓòÉΓòÉ 96.1.6. CODE ΓòÉΓòÉΓòÉ

The error code from the last action.


ΓòÉΓòÉΓòÉ 96.1.7. REASON ΓòÉΓòÉΓòÉ

The error message resulting from the last action that caused an error.


ΓòÉΓòÉΓòÉ 96.2. Actions ΓòÉΓòÉΓòÉ

PRINT()              PUTSQL()
DISCARD()            OPEN()


ΓòÉΓòÉΓòÉ 96.2.1. PRINT() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇPRINT(printer,dialog,"",jobtitle)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Prints the data.

printer   is either the name of a printer, or a pointer to an open printer
          object.

dialog    One of:

   0         No print dialog
   1         Use a print dialog

""        Reserved.

jobtitle  The print job title. Not needed if printer is a pointer to a printer
          object.


ΓòÉΓòÉΓòÉ 96.2.2. PUTSQL() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇPUTSQL(database,sqlstring,datatype,sqltable,"",colnames)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Refreshes the data.

The parameters database, string, datatype, table, and colnames work in the same
way as the corresponding attributes.


ΓòÉΓòÉΓòÉ 96.2.3. DISCARD() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇDISCARD()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Deletes the table or view from the database (if DATATYPE is set to "TABLE").


ΓòÉΓòÉΓòÉ 96.2.4. OPEN() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇOPEN()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Opens a window on the Data viewer.


ΓòÉΓòÉΓòÉ 96.3. Examples ΓòÉΓòÉΓòÉ

! Opening a Data viewer on the result of running some SQL

DEFINE MySQL[0]
INSERT MySQL[0] = "SELECT * FROM USERID.Staff"

OPEN IBMSQLTABLE MySQLTab,
 DATABASE  = "SAMPLE",
 DATATYPE  = "STRING",
 SQLSTRING = POINTER(MySQL[0])

CALL MySQLTab'OPEN()

! Updating the open Data viewer with the result of different SQL

DEFINE MySQL[0]
INSERT MySQL[0] = "SELECT NAME,SALARY "
INSERT MySQL[0] = "FROM USERID.Staff "
INSERT MySQL[0] = "WHERE NAME='Smith'"

DEFINE ColNameVec[0]
INSERT ColNameVec[0] = "Name Column"
INSERT ColNameVec[0] = "Salary Column"

CALL MySQLTab'PUTSQL(
      "SAMPLE",                /* database to read data from    */
      POINTER(MySQL[0]),       /* pointer to SQL string         */
      "STRING",                /* data type                     */
      "",                      /* table name                    */
      "USERID",                /* userId                        */
      POINTER(ColNameVec[0]))  /* pointer to column names array */

! Opening a Data viewer on a table in the database

OPEN IBMSQLTABLE MySQLTab,
 DATABASE = "SAMPLE",
 DATATYPE = "TABLE",
 SQLTABLE = "USERID.ORG"

CALL MySQLTab'OPEN()

Examples source library:


ΓòÉΓòÉΓòÉ 97. IBMTABLE ΓòÉΓòÉΓòÉ

The IBMTABLE object class creates an instance of the Visualizer table editor.

Attributes

Actions

Events

Examples


ΓòÉΓòÉΓòÉ 97.1. Attributes ΓòÉΓòÉΓòÉ

CODE                  DIALOG
IDENTIFIER            INFOAREA
MODIFIED              NAME
READONLY              REASON
VIEW


ΓòÉΓòÉΓòÉ 97.1.1. CODE ΓòÉΓòÉΓòÉ

Internal error code for the most recent operation. Read-only.

Default: None


ΓòÉΓòÉΓòÉ 97.1.2. DIALOG ΓòÉΓòÉΓòÉ

This attribute may be set to 1 or 0 ("Yes" or "No") to control error dialogs.

1         A dialog is activated to handle the error condition.
0         Dialogs are suppressed, default action taken.


ΓòÉΓòÉΓòÉ 97.1.3. IDENTIFIER ΓòÉΓòÉΓòÉ

This attribute must be set to the complete path and name of the table to be
edited.


ΓòÉΓòÉΓòÉ 97.1.4. INFOAREA ΓòÉΓòÉΓòÉ

Boolean flag to turn the information area on (1) and off (0).

Default: 1


ΓòÉΓòÉΓòÉ 97.1.5. MODIFIED ΓòÉΓòÉΓòÉ

This attribute indicates whether the object has been modified since it was last
saved.

1         Object has been modified.
0         Object has not been modified.


ΓòÉΓòÉΓòÉ 97.1.6. NAME ΓòÉΓòÉΓòÉ

This attribute may be set to the workplace object title of the table to be
opened. (NAME will be used as part of the window title.)


ΓòÉΓòÉΓòÉ 97.1.7. READONLY ΓòÉΓòÉΓòÉ

Boolean flag to indicate, when 1 (true), that the object cannot be saved onto
itself.

Default: 1 (If table is a read-only file)


ΓòÉΓòÉΓòÉ 97.1.8. REASON ΓòÉΓòÉΓòÉ

Text message of most recent error code. Read-only.

Default: None


ΓòÉΓòÉΓòÉ 97.1.9. VIEW ΓòÉΓòÉΓòÉ

This attribute determines the type of view:

o TABLE
o FORM

Default: "TABLE"


ΓòÉΓòÉΓòÉ 97.2. Actions ΓòÉΓòÉΓòÉ

COMPRESS()                COPYTO()
DISCARD()                 COLUMNS()
INQROWS()                 INQCOLPROP()
INQCOLUMNS()              INQFIXEDCOLS()
INQKEYS()                 INQTYPES()
JOIN()                    OPEN()
PRINT()                   REFRESH()
SAVE()                    SEND()
SETCOLPROP()              SETCOLUMNS()
SETROWS()                 SETFIXEDCOLS()
SPLIT()


ΓòÉΓòÉΓòÉ 97.2.1. COMPRESS() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇCOMPRESS()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

The COMPRESS action causes a table compress to take place. Savings in space
will not be seen until a SAVE() action occurs.

If successful, 0 will be returned, otherwise an error code will be returned.


ΓòÉΓòÉΓòÉ 97.2.2. COPYTO() ΓòÉΓòÉΓòÉ

                     ΓöîΓöÇ"IBMTABLE"ΓöÇΓöÉ
ΓöÇΓöÇCOPYTO(filename,ΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                     ΓööΓöÇformatΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

The current data is copied to the fully qualified file specified in filename.
If you require a specific file format, specify format as one of:

"IBMTABLE" Visualizer table (default)
"IBMTABLESUBSET" Current subset in Visualizer table format
"IXF"     Integration exchange format
"PCIXF"   PC version of IXF supported by DB2 for OS/2
"DIF"     data interchange format
"EDIF"    extended DIF
"FLAT"    ASCII file
"LIST"    Comma separated value (CSV) file
"DBF"     dBase III format.

If successful, 0 will be returned, otherwise an error code will be returned.


ΓòÉΓòÉΓòÉ 97.2.3. DISCARD() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇDISCARD()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

The DISCARD action deletes the instance of the object.


ΓòÉΓòÉΓòÉ 97.2.4. COLUMNS() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇCOLUMNS(pcolumns)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

pcolumns identifies a vector in which the names of the columns are returned.
The names are ordered by their ORDER attribute (this is the order they are
normally displayed).


ΓòÉΓòÉΓòÉ 97.2.5. INQROWS() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇINQROWS(pointer)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

pointer identifies a variable to be filled with the current subset rows
expression.


ΓòÉΓòÉΓòÉ 97.2.6. INQCOLPROP() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇINQCOLPROP(column_name,property,pvalue)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Fills the variable pointed to by pvalue with the value of a table or column
property.

column_name is the name of the column or is "" for a table property property is
one of: TYPE, COLDESC, TABDESC, EXPRESSION, RANGES, FORMAT or NULL as described
in the SETCOLPROP() action. FORMAT is for numeric columns only.

The return value is:

0         Property value returned
-1        Incorrect column name
-2        Incorrect property name
-3        Pointer to the variable not valid.


ΓòÉΓòÉΓòÉ 97.2.7. INQCOLUMNS() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇINQCOLUMNS(columns)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

pcolumns identifies a vector to be filled with the list of displayed columns
(in the order they are selected for display).


ΓòÉΓòÉΓòÉ 97.2.8. INQFIXEDCOLS() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇINQFIXEDCOLS(pkeys,pcolumns)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action sets the variable pointed to by pkeys to 1 if key columns are fixed
or to 0 if key columns are not fixed.

This action fills the vector pointed to by pcolumns with a list of fixed
columns. The action returns 0 if a list of fixed columns was returned or -1 if
one of the parameters was not valid.


ΓòÉΓòÉΓòÉ 97.2.9. INQKEYS() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇINQKEYS(pkeys)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action fills the vector pointed to by pkeys with a list of table keys. The
keys are in ascending order. Names of descending keys are preceded by a - sign.


ΓòÉΓòÉΓòÉ 97.2.10. INQTYPES() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇINQTYPES(ptypes)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action fills the vector pointed to by ptypes with the types of table
columns. Columns are ordered by their ORDER attribute.


ΓòÉΓòÉΓòÉ 97.2.11. JOIN() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇJOIN(column_1,column_2,character)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Joins two nonkey columns. The new column has the same name as column_1.
character is the separator character to use to divide the sections of the new
column.

The return value is:

0         Join successful
-1        Incorrect column name, or a keyed column was used
-2        Unusable separator character
-3        Join failed.


ΓòÉΓòÉΓòÉ 97.2.12. OPEN() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇOPEN()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

The OPEN action puts a view of the object on the screen.


ΓòÉΓòÉΓòÉ 97.2.13. PRINT() ΓòÉΓòÉΓòÉ

                                        ΓöîΓöÇ"TABLE"ΓöÇΓöÉ
ΓöÇΓöÇPRINT(ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ,ΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
           ΓööΓöÇnameΓöÇΓöÿ   ΓööΓöÇprintdialogΓöÇΓöÿ   ΓööΓöÇmethodΓöÇΓöÇΓöÿ

The PRINT action generates output suitable for printing or plotting. name is an
optional parameter indicating the name of the printer to use (the printer name
is the device name of a Workplace Shell printer object), or is a pointer to an
open printer object.

If the printer name has not been specified and the object was opened with the
DIALOG attribute set to 1 (the default), then a standard screen dialog is
invoked which presents the end user with a list of the available printers.

If the printer name has not been specified and the object was opened with
DIALOG set to 0, then the default printer is used. The default printer is
specified by the OS/2 Print Manager.

If name is a pointer to a printer or if DIALOG is 0, the value of printdialog
is ignored.

Otherwise, printdialog is used to determine whether print dialogs should be
surfaced or not. That is, if printdialog is not specified, dialogs are surfaced
if the DIALOG attribute is set to 1 and Review print options on the Profile
notebook is set.

method is an optional parameter with:

TABLE     the entire table is to be printed
SUBSET    the displayed rows and columns are to be printed


ΓòÉΓòÉΓòÉ 97.2.14. REFRESH() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇREFRESH()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

The REFRESH action surfaces the object's primary window.


ΓòÉΓòÉΓòÉ 97.2.15. SAVE() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSAVE()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

The SAVE action saves the object.


ΓòÉΓòÉΓòÉ 97.2.16. SEND() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSEND(pFormats)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action mails copies of the table in the specified formats. pFormats points
to a vector of format names. (See COPYTO() for values for pFormats.)


ΓòÉΓòÉΓòÉ 97.2.17. SETCOLPROP() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSETCOLPROP(column_name,property,new_value)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Updates one of a set of table or column properties. column_name is the name of
the column or "" for a table property.

property is one of the following:

FORMAT    Format of the column (for numeric columns only)
WIDTH     Display width of the column (1 to 254)
TYPE      Type of column (character, numeric, date, time, or graphic)
COLDESC   First level help column description
TABDESC   Table comment property
EXPRESSION Expression to check data (for example,  salary<20000)
RANGES    Range check (for example,  100:200)
NULL      NULL check condition:

   1         NULLs allowed
   2         NULLs replaced with default value
   3         NULLs not allowed
DEFAULT   Default value

The return value is:

0         Property change was successful
-1        Incorrect column name
-2        Incorrect property name
-3        Incorrect value for new property


ΓòÉΓòÉΓòÉ 97.2.18. SETCOLUMNS() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSETCOLUMNS(pcolumns)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

pcolumns identifies a vector holding a list of columns to be displayed. The
return value is -1 when an incorrect column name was found in the list.


ΓòÉΓòÉΓòÉ 97.2.19. SETROWS() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSETROWS(rowexp)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Sets the rows to be displayed. rowexp is a new subset rows expression such as:
AnnualSalary>100000. The return value is -1 when an incorrect row expression is
supplied.


ΓòÉΓòÉΓòÉ 97.2.20. SETFIXEDCOLS() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSETFIXEDCOLS(fixkeys,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                          ΓööΓöÇpcolumnsΓöÇΓöÿ

If fixkeys is 1, the key columns are fixed. If 0, then a pointer to a vector
holding a list of columns to be fixed must be specified in pcolumns.

The return value is -1 when incorrect parameters were used, or -2 when an
incorrect column name was found in the list.


ΓòÉΓòÉΓòÉ 97.2.21. SPLIT() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSPLIT(column_name,split_type,character)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Splits a column into one or more columns. column_name is the name of the column
to split. split_type is:

o "Separator" if the columns are to be split at occurrences of character.

o "Position" if the columns are to be split at the character position specified
  in character.
character is either the separator character to use, or the character position
of the split.

The return value is the number of columns created from the specified column,
or:

-1        Incorrect column name
-2        Incorrect separator or character position
-3        Incorrect split type
-4        Split failed.


ΓòÉΓòÉΓòÉ 97.3. Events ΓòÉΓòÉΓòÉ

DATASELECT("ROW", rownum, pValues)                 QUIT


ΓòÉΓòÉΓòÉ 97.3.1. DATASELECT("ROW",rownum,pValues) ΓòÉΓòÉΓòÉ

Signaled when the user selects a single row, or when a row is selected as a
result of an action such as Find or Power Insert, or when a different row is
displayed in Form view.

The first parameter is always "ROW".

rownum is the table row number of the selected row. If the row is an
unvalidated new row in the Table view, then rownum is negative.

pValues is a pointer to a vector containing the values in the selected row. If
the selected row is in the Table view and has unvalidated values, then the
vector contains these unvalidated values. The values are ordered by the
columns' Position attributes, not by the columns' positions in the current
column subset.


ΓòÉΓòÉΓòÉ 97.3.2. QUIT ΓòÉΓòÉΓòÉ

This event is signaled whenever the object handler has been requested by the
user to terminate. Use A.System.Object to identify the object handler in
question, and to issue API calls prior to shutting the object.


ΓòÉΓòÉΓòÉ 97.4. Examples ΓòÉΓòÉΓòÉ

Sample code to open a IBMTABLE object.

OPEN IBMTABLE MyTab,
 NAME       = "Employee data",
 IDENTIFIER = "D:\DSS\SAMPLES\ENU\EMPDATA"

! split the Name column into first name and last name
CALL MyTab'SPLIT("Name", "Separator", ",")

! fix the key columns in the table view
CALL MyTab'SETFIXEDCOLS(1)

! show only members of "Sales" division with no commission
LET SubsetRows = 'Division = "Sales" & Commission = 0'
CALL MyTab'SETROWS(SubsetRows)

! now show the table
CALL MyTab'OPEN()

Examples source library:


ΓòÉΓòÉΓòÉ 98. IF ... THEN ... ELSE ΓòÉΓòÉΓòÉ

The IF, THEN, and ELSE statements form a group that directs the flow of control
in a program.

The IF statement tests the result of a condition.

The THEN statement introduces a statement or set of statements to be executed
when the IF condition is true.

The ELSE statement introduces a statement or set of statements to be executed
when the IF condition is false.

ΓöÇΓöÇIFΓöÇΓöÇconditionΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇstatementlist1ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                   ΓööΓöÇTHENΓöÇΓöÿ                  ΓööΓöÇELSEΓöÇΓöÇstatementlist2ΓöÇΓöÿ

Examples

More about IF ... THEN ... ELSE

See also: CASE...WHEN...OTHERWISE...END, ELSE, NOTHING, THEN


ΓòÉΓòÉΓòÉ 98.1. Examples ΓòÉΓòÉΓòÉ

IF x > 0
  Total += x
ELSE
  Total = 0

IF Status = "Open" & Action = "Update"
DO
  IF Changed
  DO
     CALL UPDATE()
     LET UpdateCount +=1
  END
END

IF day="Friday" & time="5"
THEN a = 1
ELSE DO
  a = 2
  STR1 = "Are you working this weekend?"
END

IF OK
THEN
  CALL UPDATE()
ELSE DO
  IF Status = "Open"
  CALL RESTORE()
END

Examples source library:


ΓòÉΓòÉΓòÉ 98.2. More about IF ... THEN ... ELSE ΓòÉΓòÉΓòÉ

o The condition is true, and the THEN block is executed, in the following
  cases:

   - condition is numeric and nonzero
   - condition is character and has a length of 1 or more

  Note:   Even a character string containing a single space ( " ") has a length
          of 1.

o The condition is false, and the ELSE block is executed (if there is one), in
  the following cases:

   - condition is numeric and zero
   - condition is character and is an empty string ( "")
   - condition is NULL

  Note:   NULL is not the same as an empty string ( ""), but the IF statement
          treats both as false.

o You can use comparison operators as part of condition. Comparison operators
  return a numeric result of 1 (true), or 0 (false) if the comparison is valid.
  They return a result of NULL (false) if either of the values being compared
  is NULL. For a list of comparison operators, see Comparisons.

o IF, THEN, and ELSE can introduce a single statement or multiple statements.
  If they introduce multiple statements, then you must enclose the statements
  in a DO ... END block.

o You can type the statement following THEN or ELSE either on the same line, or
  on a separate line.

o You can nest IF statements, even if you do not use DO ... END blocks. For
  example:

    IF alpha
      THEN IF beta
        THEN z = 0     /* alpha was true and beta was true              */
        ELSE z = 1     /* alpha was true but beta was false or NULL     */

    IF alpha
    THEN DO
      IF beta
        THEN z = 0     /* alpha was true and beta was true              */
    END
    ELSE z = 1         /* alpha was false or NULL                       */

    IF alpha
      THEN z = 0       /* alpha was true                                */
      ELSE IF beta
        THEN IF gamma
          THEN z = 1   /* alpha false or NULL, beta and gamma true      */
          ELSE z = 2   /* alpha false/NULL, beta true, gamma false/NULL */
        ELSE z = 3     /* alpha and beta were false or NULL             */


ΓòÉΓòÉΓòÉ 99. IF() ΓòÉΓòÉΓòÉ

The IF() function tests a condition and returns one of three expressions as a
result.

ΓöÇΓöÇIF(condition,trueexpr,falseexpr,nullexpr)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Examples

More about IF()

See also: IF ... THEN ... ELSE


ΓòÉΓòÉΓòÉ 99.1. Examples ΓòÉΓòÉΓòÉ

LET Angle = 75
LET result = IF(Angle < 90, 'Acute', 'Obtuse')   ! result is 'Acute'

LET Amount = -23.50
LET result = IF(Amount >= 0, "Credit", "Debit", "Unknown")
                                                 ! result is "Debit"
IF IF(a > b, a, b) > limit
THEN DO ...

Examples source library:


ΓòÉΓòÉΓòÉ 99.2. More about IF() ΓòÉΓòÉΓòÉ

o Any of the three return expressions can be omitted, but all the commas shown
  in the syntax diagram must be inserted. If the appropriate expression is not
  present, IF() returns NULL.

o The IF() function simplifies coding by avoiding repeated expressions, and the
  expressions to be returned can be evaluated at run time.

o All the expressions are evaluated, even if they are not selected by
  condition.


ΓòÉΓòÉΓòÉ 100. INDEX ΓòÉΓòÉΓòÉ

The INDEX statement creates a vector of numbers which identifies the sequence
for the values in an array or in the columns of a table.

                   <ΓöÇ,ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöÇΓöÇINDEXΓöÇΓöÇorder=ΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇcolumnΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                     ΓööΓöÇ-ΓöÇΓöÿ

Examples

More about INDEX


ΓòÉΓòÉΓòÉ 100.1. Examples ΓòÉΓòÉΓòÉ

INDEX deptseq = employee.Division, employee.Department
! 'deptseq' indexes the 'employee' table rows
! sorted by division, and by department within each division

INDEX empsal = -employee.AnnualSalary, employee.Name
! 'deptseq' indexes the 'employee' table rows
! sorted by salary (in descending order), and in name order
! among people with the same salary

! Here, we open a listbox to show a vector of numbers
! sorted into ascending order
DEFINE datalist[0]
INSERT datalist[0] = 15
INSERT datalist[0] = NULL
INSERT datalist[0] = 4
INSERT datalist[0] = 57
INSERT datalist[0] = -45

DEFINE listexpr[1] = "WIDTH=100"
DEFINE listref[1]  = datalist[0]

INDEX order = -?"datalist"
OPEN LIST numberlist, MyWin,
 X = 8, Y = 6,
 SIZEX = 100, SIZEY = 100,
 EXPRESSION = listexpr[0],
 REFERENCE = listref[0],
 ORDERDATA = order[0]

Examples source library:


ΓòÉΓòÉΓòÉ 100.2. More about INDEX ΓòÉΓòÉΓòÉ

o The INDEX statement allows the rows of a table to be processed in any
  sequence without having to produce new copies of the table with the columns
  in the new order.

o References to elements in the new sequence require the use of nested square
  brackets.  For example, to return the lowest number in a list of random
  numbers named datalist which has been resequenced in ascending order by INDEX
  using the vector sorted:

    LET lowest = datalist[order[1]]

o In the case of duplicate values, the original sequence is preserved.

o The order vector created by INDEX is unaffected if entries are added or
  replaced in the original vector.  It can therefore be necessary to repeat the
  INDEX statement or, alternatively, to update the index vector whenever the
  original vector is modified.

o With the exception of NULL values, all values in a column must be of a
  consistent type.

o Any NULL values are collated to the end of order.


ΓòÉΓòÉΓòÉ 101. INSERT ΓòÉΓòÉΓòÉ

The INSERT statement has two uses:

o To insert an element into a vector
o To insert a row into a table.

ΓöÇΓöÇINSERTΓöÇΓöÇreferenceΓöÇΓöÇΓö¼ΓöÇ[ΓöÇΓöÇexpressionΓöÇΓöÇ]ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                       Γöé    <ΓöÇ,ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ    Γöé  ΓööΓöÇ=valueΓöÇΓöÿ
                       ΓööΓöÇ{ΓöÇΓöÇΓöÇΓöÇexpression1ΓöÇΓö┤ΓöÇΓöÇ}ΓöÇ]

Examples

More about INSERT

See also: INSERT(), LET


ΓòÉΓòÉΓòÉ 101.1. Examples ΓòÉΓòÉΓòÉ

To define a vector and insert some elements into it:

DEFINE vec[3]
LET    vec[1] = "Wednesday"
LET    vec[2] = "Friday"
LET    vec[3] = "Saturday"

INSERT vec[2] = "Thursday"   /* insert Thursday between Wednesday and Friday */
INSERT vec[1] = "Tuesday"    /* insert Tuesday at the beginning              */
INSERT vec[1] = "Monday"     /* insert Monday at the beginning               */
INSERT vec[7] = "Sunday"     /* insert Sunday at the end                     */

More examples of INSERT:

INSERT counts[24]
INSERT staff.number{"Smith", 87367}
INSERT totals[area] = 0

Examples source library:


ΓòÉΓòÉΓòÉ 101.2. More about INSERT ΓòÉΓòÉΓòÉ

o When an element is inserted into a one-dimensional array, then the number of
  elements in the array is incremented by one, and the relative positions of
  all elements after the one inserted are increased by one.

               x                         INSERT x [3]="Y"
    ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ         ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
    Γöé A  B  C  D  E  F  G Γöé         Γöé A  B  Y  C  D  E  F  G Γöé
    ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ         ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
      1  2  3  4  5  6  7             1  2  3  4  5  6  7  8

o To insert a row into a table, you need only name one column of the table and
  specify values for the key columns. The elements from other columns, which
  make up the rest of the row, are automatically created with NULL values.

o Inserting into a table will not produce a duplicate key. If a duplicate key
  is specified, the value of the referenced column will be replaced with the
  value given. You cannot insert by position (square-bracket reference) into a
  table.  An initial value cannot be assigned to a key.

o After using INSERT, you can assign values to that array element or table row
  when you want to.  For example:

    INSERT x[9]
    LET x[9] = "Moomin"

  This will have the same effect as:

    INSERT x[9] = "Moomin"

o INSERT is not valid for two-dimensional arrays.

o A new element can be added at the end of a vector by inserting at position
  zero. For example:

    DEFINE vec[0]
    INSERT vec[0] = "First entry"
    INSERT vec[0] = "Second entry"
    INSERT vec[0] = "Third entry"


ΓòÉΓòÉΓòÉ 102. INSERT() ΓòÉΓòÉΓòÉ

The INSERT() function is used in the same way as the INSERT statement:

o To insert an element into a vector
o To insert a row into a table.

In addition, INSERT() returns the index number at which the insertion was made.

ΓöÇΓöÇINSERTΓöÇΓöÇ(ΓöÇΓöÇreferenceΓöÇΓöÇΓö¼ΓöÇ[ΓöÇΓöÇexpressionΓöÇΓöÇ]ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                          Γöé    <ΓöÇ,ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ    Γöé  ΓööΓöÇ,valueΓöÇΓöÿ
                          ΓööΓöÇ{ΓöÇΓöÇΓöÇΓöÇexpression1ΓöÇΓö┤ΓöÇΓöÇ}ΓöÇ]

Examples

More about INSERT()


ΓòÉΓòÉΓòÉ 102.1. Examples ΓòÉΓòÉΓòÉ

LET newrow = INSERT(employee.Name{174773}, "Robin, Christopher")
LET employee.Sex[newrow] = 'M'
LET employee.Salary[newrow] = 24500

Examples source library:


ΓòÉΓòÉΓòÉ 102.2. More about INSERT() ΓòÉΓòÉΓòÉ

o See the definition of the INSERT statement for full details ( INSERT).


ΓòÉΓòÉΓòÉ 103. INSSOSI() ΓòÉΓòÉΓòÉ

The INSSOSI() function inserts Shift Out (SO) and Shift In (SI) control codes
at the boundaries of groups of SBCS and DBCS characters in a string.

ΓöÇΓöÇINSSOSI(string)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Examples

More about INSSOSI()

See also: RMVSOSI()


ΓòÉΓòÉΓòÉ 103.1. Examples ΓòÉΓòÉΓòÉ

In this example, s represents a single-byte character, D1, D2, and D3 repres
double-byte characters, and > and  < represent SO and SI control codes.

LET string = "ssssD1D2D3ssss"
LET result = INSSOSI(string)

The string result contains "ssss>D1D2D3<ssss".

Examples source library:


ΓòÉΓòÉΓòÉ 103.2. More about INSSOSI() ΓòÉΓòÉΓòÉ

o The result of this function is always a string of type CHARACTER.

o The code points for the SO and SI control codes are X'0E' and X'0F'.

o This function can be used for making an IXF file for sending to a host
  environment.  It can also be used to differentiate character types, which is
  helpful when calculating string lengths in a host environment.


ΓòÉΓòÉΓòÉ 104. ITERATE ΓòÉΓòÉΓòÉ

The ITERATE statement is used within repeating blocks to start immediately a
fresh iteration of one of the blocks in which it is contained. ITERATE
transfers control to the next END statement or to the referenced END statement.

ΓöÇΓöÇITERATEΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
             ΓööΓöÇnumberΓöÇΓöÿ

Examples

More about ITERATE

See also: DO...END, END, LEAVE, TERMINATE, UNTIL, WHILE


ΓòÉΓòÉΓòÉ 104.1. Examples ΓòÉΓòÉΓòÉ

The example below reads through a vector and counts how many elements have the
value "MACK".

DEFINE program[5] = "LET x = 1"
LET    program[2] = "! this is a comment"
LET    program[3] = "! and so is this"
CALL format_code(POINTER(program[0]))

PROCEDURE format_code(pVector)
DO
  DECLARE POINTER pVector
  DECLARE NUMERIC i

  ! This function formats our code nicely

  DO i = 1 : (?pVector)[0]'ENTRIES
    IF SPLIT((?pVector)[i], 1, 1) = "!"
    THEN ITERATE          /* this line is a comment - leave it alone */

    CASE WORD((?pVector)[i], 1)
      WHEN "LET"
      DO
        ...
    END
  END
END


!
! Now we count the number of lines in a piece of text
! which do NOT contain any of the following fish
!
DEFINE fish[0]
INSERT fish[0] = "halibut"
INSERT fish[0] = "hake"
INSERT fish[0] = "haddock"

DEFINE woolf[0]
INSERT woolf[0] = "And now with some pleasure I find that it's seven;"
INSERT woolf[0] = "and must cook dinner. Haddock and sausage meat."
INSERT woolf[0] = "I think it is true that one gains a certain hold on"
INSERT woolf[0] = "sausage and haddock by writing them down."

LET fishless = count_fishfree_lines(POINTER(woolf[0]))

PROCEDURE count_fishfree_lines(pText)
DO
  DECLARE POINTER pText
  DECLARE NUMERIC line
  DECLARE NUMERIC word
  DECLARE CHAR[*] thisline
  DECLARE CLEAR NUMERIC result

  DO line = 1 : (?pText)[0]'ENTRIES
    LET thisline = (?pText)[line]
    DO word = 1 : WORDS(thisline)
      IF FIND(fish, WORDS(thisline, word,, 1)) != 0  /* fishy string */
      THEN ITERATE 2                    /* move on to the next string */
    END
    LET result += 1
  END

  RETURN result
END

Examples source library:


ΓòÉΓòÉΓòÉ 104.2. More about ITERATE ΓòÉΓòÉΓòÉ

o ITERATE can be used in repeating DO ... END blocks, and in WHILE and UNTIL
  blocks.

o Nonrepeating DO ... END blocks are ignored. (Use the LEAVE statement to exit
  from a nonrepeating DO ... END block.)


ΓòÉΓòÉΓòÉ 105. LEAVE ΓòÉΓòÉΓòÉ

The LEAVE statement terminates one or more active DO ... END blocks.

By default, LEAVE terminates only the current DO ... END block. Where DO ...
END blocks are nested (several are active at once), LEAVE can specify the
number of blocks to be terminated.

ΓöÇΓöÇLEAVEΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
           ΓööΓöÇnumberΓöÇΓöÿ

Examples

More about LEAVE

See also: DO...END, ITERATE, RETURN, TERMINATE, UNTIL, WHILE


ΓòÉΓòÉΓòÉ 105.1. Examples ΓòÉΓòÉΓòÉ

IF \NULL(pFile)
THEN DO
  IF changes > 0
  THEN DO
    IF DIALOG("FTB0008", 0, "This file has changed. Save changes?") = "NO"
    THEN LEAVE

    IF (?pFile)'CLASS \= "FILE"
    THEN DO
      ERROR 1, "Internal error - the data cannot be saved"
      LEAVE 3   /* this will resume at the RETURN statement */
    END

    CALL save_changes(pFile)
    LET changes = 0
  END
  SHUT ?pFile
END
RETURN foo

Examples source library:


ΓòÉΓòÉΓòÉ 105.2. More about LEAVE ΓòÉΓòÉΓòÉ

o LEAVE can terminate repeating and nonrepeating blocks. You can use LEAVE in
  repeating DO ... END blocks, and in WHILE and UNTIL blocks.

o A LEAVE statement that terminates the DO block of a PROCEDURE or an ON block
  ends that block. It is therefore equivalent to RETURN.


ΓòÉΓòÉΓòÉ 106. LENGTH() ΓòÉΓòÉΓòÉ

The LENGTH() function returns the number of bytes in a string or the largest
number of characters in any element from a range of elements in an array. It
can also be used for numeric, date, and time values.

                    ΓöîΓöÇ1ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöÇΓöÇLENGTH(express,ΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇ,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                    ΓööΓöÇstartΓöÇΓöÿ   ΓööΓöÇendΓöÇΓöÿ   ΓööΓöÇsepΓöÇΓöÿ

Examples

More about LENGTH()

See also: CLENGTH()


ΓòÉΓòÉΓòÉ 106.1. Examples ΓòÉΓòÉΓòÉ

String = "Eric the Red"
Result = LENGTH(String)                    ! Result is 12

DEFINE StringArray[4]
StringArray[1] = "Laser Printer"
StringArray[2] = "Ink Jet Printer"
StringArray[3] = "Other Printers..."
Result = LENGTH(StringArray)               ! Result is 17
Result = LENGTH(StringArray,1,2)           ! Result is 15
Result = LENGTH(StringArray,,,"." )        ! Result is 15

Examples source library:


ΓòÉΓòÉΓòÉ 106.2. More about LENGTH() ΓòÉΓòÉΓòÉ

o For a character value, the number of characters (including leading and
  trailing blanks) is returned.

  For numeric, date, and time values, the length of the character
  representation of the value (as defined by the FORMAT attribute) is given.

o DBCS characters cannot be used as separators.  However, when an SBCS space is
  specified as separator, both SBCS and DBCS trailing spaces are excluded from
  the count of characters.


ΓòÉΓòÉΓòÉ 107. LET ΓòÉΓòÉΓòÉ

The LET statement is used to set values held in variables, array elements, and
attributes, including dictionary or element attributes.

The keyword LET is optional.

ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇreferenceΓöÇΓöÇoperatorΓöÇΓöÇexpressionΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
    ΓööΓöÇLETΓöÇΓöÿ

Examples

More about LET


ΓòÉΓòÉΓòÉ 107.1. Examples ΓòÉΓòÉΓòÉ

LET Rate = 10.5
LET Count += Count             !  Doubles Count.
LET Names[4] = "Jones"
Sales = ?Amount
?Work = Total1 + Total2
LET let = "Hindrance"          !  Using a statement keyword.
Window[4]'SIZEX -=10
Staff.Salary[0]'TYPE = "Numeric"

Use the left and right braces {} when using a key in a table.  Note that this
example uses parenthesis around the indirection symbol and the table name.

LET (?Credit){"Jones"}'COLOR = "Red"

Examples source library:


ΓòÉΓòÉΓòÉ 107.2. More about LET ΓòÉΓòÉΓòÉ

o The keyword LET can be omitted when the remainder of the statement does not
  begin with an item that could be interpreted as a statement keyword.

o If reference does not exist, it is created automatically as a scalar when the
  statement is executed.

o All compound assignments can be expanded in a similar way to the following:

    LET A += B

  is equivalent to:

    LET A = A + B

o reference takes the data type of expression unless it is a variable which has
  a dictionary type set, in which case a conversion is performed.


ΓòÉΓòÉΓòÉ 108. LIBRARY ASL, LIBRARY DLL, LIBRARY REXX ΓòÉΓòÉΓòÉ

The LIBRARY ASL statement allows shared access to commonly used procedures and
functions.

LIBRARY DLL allows access to routines saved as DLL format files. Typically
these will be C routines.

LIBRARY REXX allows access to command files found in the current path, and to
REXX function libraries.

                                             <ΓöÇ,ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöÇΓöÇLIBRARYΓöÇΓöÇΓö¼ΓöÇASLΓöÇΓöÇ"library_name"ΓöÇΓö¼ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇroutineΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
             Γö£ΓöÇDLLΓöÇΓöÇ"dll_name"ΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ  ΓööΓöÇ,ΓöÇΓöÿ
             ΓööΓöÇREXXΓöÇΓöÇ"location"ΓöÇΓöÇΓöÇΓöÇΓöÿ

Examples

More about LIBRARY ASL, LIBRARY DLL, and LIBRARY REXX

See also: LIBRARY ENTRY, OPEN

Also see Using the C programming language.


ΓòÉΓòÉΓòÉ 108.1. Examples ΓòÉΓòÉΓòÉ

OPEN OBJECTSTORE Mylib,
 NAME = "mylib.a95",
 LOCATION = "D:\DSS"

LIBRARY ASL "Mylib.modules.Appdevl",
 Files,
 App_Icon

Allows access to the functions in the Mylib ASL library and permits later calls
to the listed functions, Files and App_Icon.

LIBRARY DLL "Mathlib" hyp_sin

Allows access to the functions in the Mathlib DLL library and makes a function
called  hyp_sin available.

LIBRARY REXX "", FileFind

Allows access to FILEFIND.CMD, which must be in a directory on the default
system path.

Examples source library:


ΓòÉΓòÉΓòÉ 108.2. More about LIBRARY ASL, LIBRARY DLL, and LIBRARY REXX ΓòÉΓòÉΓòÉ

o The first reference in the application to any routine in that library causes
  the library to be started. It remains available until the application is
  closed.

o The OBJECTSTORE in which an ASL library is stored must be open before a
  library can be accessed.

o ASL libraries created with Visualizer must have a file extension of .A95

o Tasks within an application share libraries within that application.

o A Visualizer library module can have an ON START block which is executed when
  the library is started.

o Visualizer library procedures have their own local task (T..) variables
  shared between all routines in that library. They can access the general
  (A..) variables of an application.

o It is possible to access some features of the ASL language from within a C
  program in a DLL library.

o A REXX command file can be in a specific named directory or, if location is
  "", then it can be anywhere on the system path.

  If location does not contain any path characters such as backslash ( \) or
  colon ( :), then it is taken to be the name of a REXX function library (for
  example, REXXUTIL).

o Since the LIBRARY statement is declarative, it does not need to be inside an
  ON block.


ΓòÉΓòÉΓòÉ 109. LIBRARY ENTRY ΓòÉΓòÉΓòÉ

The LIBRARY ENTRY statement allows an application to declare which of its
procedures and functions can be called as library routines.

                    <ΓöÇ,ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöÇΓöÇLIBRARYΓöÇΓöÇENTRYΓöÇΓöÇΓöÇΓöÇroutineΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Examples

More about LIBRARY ENTRY

See also: LIBRARY ASL, LIBRARY DLL, LIBRARY REXX

Also see Using the C programming language.


ΓòÉΓòÉΓòÉ 109.1. Examples ΓòÉΓòÉΓòÉ

LIBRARY ENTRY hyp_sin, hyp_cos, hyp_tan
...
PROCEDURE hyp_sin(arg)
...

This example declares the three hyp functions to be public. Other functions and
procedures within this application cannot be accessed by other applications.

Examples source library:


ΓòÉΓòÉΓòÉ 109.2. More about LIBRARY ENTRY ΓòÉΓòÉΓòÉ

o The library code accesses its own set of local (T..) variables.

o The library is closed when the calling application stops.

o An application which wishes to call any of these functions must use the
  LIBRARY ASL statement.

o Since the LIBRARY ENTRY statement is declarative, not executable, it does not
  need to be inside an ON block.


ΓòÉΓòÉΓòÉ 110. LIBRARY LOCAL ΓòÉΓòÉΓòÉ

The LIBRARY LOCAL statement allows a program to indicate which of its
procedures can be called indirectly.

                   <ΓöÇ,ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöÇΓöÇLIBRARY LOCALΓöÇΓöÇΓöÇΓöÇprocedureΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Examples

More about LIBRARY LOCAL

See also: CALL, PROCEDURE, PROCEDURE()


ΓòÉΓòÉΓòÉ 110.1. Examples ΓòÉΓòÉΓòÉ

LIBRARY LOCAL msg_OK, msg_Cancel, other_proc
...
LET callproc = "msg_" ~
               DIALOG("FTB10005", 0, "This will erase all your files, OK?")
CALL (?PROCEDURE(callproc))(parm)
...
PROCEDURE msg_OK(arg)
DO
...

Examples source library:


ΓòÉΓòÉΓòÉ 110.2. More about LIBRARY LOCAL ΓòÉΓòÉΓòÉ

o The LIBRARY LOCAL statement declares which procedures can be used in calls to
  the PROCEDURE() function, which creates a pointer to a procedure. Since a
  procedure can be called indirectly only if there is a pointer to it, LIBRARY
  LOCAL effectively restricts the use of indirect procedure calls.

o If there is no LIBRARY LOCAL statement in a program, any local procedure can
  be called indirectly.

o Because the LIBRARY LOCAL statement is declarative, not executable, it can be
  placed anywhere in the program; it does not have to be within an ON block.


ΓòÉΓòÉΓòÉ 111. LINE ΓòÉΓòÉΓòÉ

The LINE graphics primitive object class creates an instance of a line.

Parent: DEFINE

Attributes

Actions: None.

Events: None.

Examples


ΓòÉΓòÉΓòÉ 111.1. Attributes ΓòÉΓòÉΓòÉ

CLOSINGLINE            ENCLOSED
REFERENCE

The following standard graphics attributes are also available. They are
described in Standard graphics attributes.

BOUNDED                FILLCOLOR
LINEWIDTH              SELECTED
COLOR                  FILLPATTERN
MIX                    VISIBLE
CONSTANT               LINESTYLE
SELECTABLE


ΓòÉΓòÉΓòÉ 111.1.1. CLOSINGLINE ΓòÉΓòÉΓòÉ

Whether the area is closed with a line joining the first point to the last:

0         Area not closed (default)
1         Area closed


ΓòÉΓòÉΓòÉ 111.1.2. ENCLOSED ΓòÉΓòÉΓòÉ

Whether the line is treated as a closed object which can be filled:

0         Line not enclosed (default)
1         Line enclosed


ΓòÉΓòÉΓòÉ 111.1.3. REFERENCE ΓòÉΓòÉΓòÉ

Vector defining points on the line. This vector consists of the following
elements:

1         X coordinate of the first point on the line.
2         Y coordinate of the first point on the line.
3         X coordinate of the second point on the line.
4         Y coordinate of the second point on the line.
5         X coordinate of the third point on the line.
6         Y coordinate of the third point on the line.

Any number of points can be defined. To start a new line which is not joined to
the preceding points, leave a blank pair of X and Y coordinates. All
coordinates are expressed in world coordinate units.

Set on OPEN, then read-only.

Default: ""


ΓòÉΓòÉΓòÉ 111.2. Examples ΓòÉΓòÉΓòÉ

! Produce two line objects on the graphics area. First example
! is a simple line, the second demonstrates the use of
! line to produce a more complex shape.

DEFINE linearr[4]
LET linearr[1] = 10             ! x start
LET linearr[2] = 50             ! y start
LET linearr[3] = 100            ! x end
LET linearr[4] = 190            ! y end
OPEN LINE line1, def1,
 REFERENCE = linearr[0],
 COLOR = 2,
 LINESTYLE = 0,
 LINEWIDTH = 2,
 CONSTANT = 1
!

! To produce a more complex shape
! add extra details to the reference array
!
DEFINE linearr[0]
LET x = 250
LET y = 50
LET increment = 10
LET size = 100
DO i = 1 : 10
  INSERT linearr[0] = x
  INSERT linearr[0] = y
  INSERT linearr[0] = x
  INSERT linearr[0] = y+size
  INSERT linearr[0] = x+size
  INSERT linearr[0] = y+size
  LET y + = increment
  INSERT linearr[0] = x+size
  INSERT linearr[0] = y
  LET x + = increment
  LET size = size - 0.75*increment
END

OPEN LINE line2, def1,
 REFERENCE = linearr[0],
 COLOR = 3,
 LINESTYLE = 0,
 LINEWIDTH = 1,
 CONSTANT = 1

Examples source library:


ΓòÉΓòÉΓòÉ 112. LINE() ΓòÉΓòÉΓòÉ

The LINE() function returns a format value which specifies that one or more new
lines are required in the output file when this value is written to an output
device (such as a printer) which supports lines of output.

ΓöÇΓöÇLINEΓöÇΓöÇ(ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
             ΓööΓöÇexpressionΓöÇΓöÿ

Examples

More about LINE()

See also: FILE, PAGE(), PRINTER, SPACE()


ΓòÉΓòÉΓòÉ 112.1. Examples ΓòÉΓòÉΓòÉ

CALL MyPrinter'PUT("Page ", Page_Num, LINE(2), "Name ", EmpName, LINE())

LET Nl=LINE()
LET Nl'COUNT = 2
LET Treble = LINE(3)
CALL MyPrinter'PUT("report2", Heading1, Nl, Heading2, Treble)

CALL FILE'PUT(record1, LINE(), record2, LINE(), record3, LINE())

In this example, the third statement shows how the COUNT attribute of a format
variable (Nl) can be changed to set the number of lines required in the output
file.

Examples source library:


ΓòÉΓòÉΓòÉ 112.2. More about LINE() ΓòÉΓòÉΓòÉ

o Format values of LINE() are displayed on the screen as LINE. The COUNT
  attribute is not displayed.

o The LINE() function can be used in PUT() actions and in LET and IF
  statements.

o LINE(n) causes  n-1 completely blank lines.

o If you wish to write a TEXT file (see the OPEN FILE statement) with separate
  records, then you should use the LINE() function (with the default parameter
  of one) to end each record.


ΓòÉΓòÉΓòÉ 113. LINK ΓòÉΓòÉΓòÉ

The LINK object provides a standard way to handle linking to DDE server
applications.

Attributes

Actions

Events

See also: DDECLIENT, DDESERVER, LINKSHOW, SOURCECTRL, TARGETCTRL, REFERENCE


ΓòÉΓòÉΓòÉ 113.1. Attributes ΓòÉΓòÉΓòÉ

APPLICATION              CODE
ACTIVE                   AUTORESTART
DEFAULTFORMAT            DIALOG
HOT                      ID
ITEM                     LOCATION
NAME                     NATIVEFORMAT
OBJECTNAME               RESTARTABLE
STARTCOMMAND             TOPIC


ΓòÉΓòÉΓòÉ 113.1.1. APPLICATION ΓòÉΓòÉΓòÉ

This attribute returns a string value representing the name of the linked
server application or object class. Its value may be used to set the
APPLICATION attribute of a DDECLIENT object when attempting to establish a DDE
conversation with the server.

Set on OPEN, then read-only.


ΓòÉΓòÉΓòÉ 113.1.2. CODE ΓòÉΓòÉΓòÉ

This attribute returns a numeric value indicating an environment error has
occurred, or 0 if the last action or attribute modification was successful.
When an error occurs, CODE is set to the error message number (except for DDE
or system errors, CODE is then the DDE or OS/2 error code).

Set on OPEN, then read-only.


ΓòÉΓòÉΓòÉ 113.1.3. ACTIVE ΓòÉΓòÉΓòÉ

This Boolean attribute is 1 (true) if the link is in DDE conversation with the
linked object, otherwise it will is 0 (false).

Set on OPEN, then read-only.


ΓòÉΓòÉΓòÉ 113.1.4. AUTORESTART ΓòÉΓòÉΓòÉ

This Boolean attribute has a default value of 0 (false). It can be set to 1
(true) if the link has obtained restart information from the server. If it is
set to 1 (true), then the link attempts to restart the server whenever an
attempt to activate fails.

Any attempt to modify AUTORESTART to 1 (true) when restart information is not
available will be rejected with an error message.


ΓòÉΓòÉΓòÉ 113.1.5. DEFAULTFORMAT ΓòÉΓòÉΓòÉ

This string attribute up to 255 bytes is supplied by the client as the default
for the format parameter in subsequent REQUEST and HOTLINK actions. If no value
is specified, or the value is specified as a NULL or a zero length character
string, the format will be determined from the server when the link has
successfully activated.


ΓòÉΓòÉΓòÉ 113.1.6. DIALOG ΓòÉΓòÉΓòÉ

This Boolean attribute controls whether error messages are reported to the
user.

Default: 1 (Messages are reported)

Set on OPEN, then read-only.


ΓòÉΓòÉΓòÉ 113.1.7. HOT ΓòÉΓòÉΓòÉ

This Boolean attribute has a value of 1 (true) or 0 (false) subject to the last
HOTLINK action on the link.

Set on OPEN, then read-only.


ΓòÉΓòÉΓòÉ 113.1.8. ID ΓòÉΓòÉΓòÉ

This read-only attribute returns a pointer value that uniquely identifies the
link. It can be used to populate the vector of link identifiers required by the
LINKSHOW object.


ΓòÉΓòÉΓòÉ 113.1.9. ITEM ΓòÉΓòÉΓòÉ

This attribute returns a string value representing a server defined item that
will be rendered on request. Its value may be used as the first argument to a
REQUEST, ADVISE or UNADVISE action on a DDECLIENT object when in conversion
with the server via DDE.

Set on OPEN, then read-only.


ΓòÉΓòÉΓòÉ 113.1.10. LOCATION ΓòÉΓòÉΓòÉ

This attribute identifies the location of a file holding information in the
NATIVEFORMAT of the linked object. It will be a fully qualified file location
in UNC (\\Domain\Resource\) or regular (Drive:\Directory\) format. (LOCATION is
used together with the NAME attribute.)

Set on OPEN, then read-only.


ΓòÉΓòÉΓòÉ 113.1.11. NAME ΓòÉΓòÉΓòÉ

The name of the file which has information in the NATIVEFORMAT of the linked
object. (The NAME attribute is used together with the LOCATION attribute.)

Set on OPEN, then read-only.


ΓòÉΓòÉΓòÉ 113.1.12. NATIVEFORMAT ΓòÉΓòÉΓòÉ

A character string that is the native format of the linked object.

If the link was created via the clipboard, then NATIVEFORMAT is not known until
the link has been successfully activated.

Set on OPEN, then read-only.


ΓòÉΓòÉΓòÉ 113.1.13. OBJECTNAME ΓòÉΓòÉΓòÉ

A character string that is the name of the linked object, as supplied by the
source. OBJECTNAME is empty ("") if the link was created from the clipboard.

Read-only.


ΓòÉΓòÉΓòÉ 113.1.14. RESTARTABLE ΓòÉΓòÉΓòÉ

This Boolean attribute has a value of 1 (true) if the link is inactive and has
received restart information from a server.

Set on OPEN, then read-only.

Default: 0 (False)


ΓòÉΓòÉΓòÉ 113.1.15. STARTCOMMAND ΓòÉΓòÉΓòÉ

If the link has obtained restart information from a server, the restart string
will be returned when this attribute is queried.

Set on OPEN, then read-only.

Default: Null


ΓòÉΓòÉΓòÉ 113.1.16. TOPIC ΓòÉΓòÉΓòÉ

This attribute returns a string value representing the topic of conversation,
or instance name, of the server. Its value may be used to set the TOPIC
attribute of a DDECLIENT object when attempting to establish a DDE conversation
with the server.

Set on OPEN, then read-only.


ΓòÉΓòÉΓòÉ 113.2. Actions ΓòÉΓòÉΓòÉ

ACTIVATE()                ADDFORMAT()
CLOSE()                   DEACTIVATE()
FORMATS()                 EQUALS()
HOTLINK()                 LOAD()
QUERYFORMATS()            REQUEST()
RESTART()                 VERIFYFORMAT()


ΓòÉΓòÉΓòÉ 113.2.1. ACTIVATE() ΓòÉΓòÉΓòÉ

              ΓöîΓöÇ60ΓöÇΓöÇΓöÇΓöÇΓöÉ   ΓöîΓöÇ0ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöÇΓöÇACTIVATE(ΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇ,ΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
              ΓööΓöÇRetryΓöÇΓöÿ   ΓööΓöÇReportΓöÇΓöÿ

This action attempts to establish a DDE conversation with the server
application.

If the attempt fails, it will be retried at an interval specified by Retry (in
seconds), until either it succeeds, or DEACTIVATE() is issued. The default for
retry is 60 seconds. If a value of 0 is specified, no retries will be
attempted. If specified, Retry must be an integer of zero or above, otherwise
an error condition will be raised.

Report is a Boolean parameter which, when 1, overrides the DIALOG attribute for
this action only.

If no DDE information is available, no DDE communication takes place, and the
available rendering formats are not determined.

This actions returns a numeric value, 0 to indicate success, or another integer
value to indicate failure.


ΓòÉΓòÉΓòÉ 113.2.2. ADDFORMAT() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇADDFORMAT(Format)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action adds the name of a data format acceptable to the client program.
Successive ADDFORMAT actions can be used to inform the link about all data
formats that it can accept. This information may be used by LINK to determine
which data format to request from a server when the client does not specify a
data format on a REQUEST or HOTLINK action.

Format must be a string value representing a data format name.


ΓòÉΓòÉΓòÉ 113.2.3. CLOSE() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇCLOSE()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action may be called to ask the link to close. The link issues a QUIT.
This signals a QUIT event in the program that opened the link.


ΓòÉΓòÉΓòÉ 113.2.4. DEACTIVATE() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇDEACTIVATE()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This actions deactivates a DDE conversation, or terminates retrying of a
previously unsuccessful ACTIVATE() request.


ΓòÉΓòÉΓòÉ 113.2.5. FORMATS() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇFORMATS(pFormats)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This actions defines a set of data formats acceptable to the client program,
replacing any existing definition of acceptable formats. This information may
be used by LINK to determine which data format to request from a server when
the client does not specify a data format on a REQUEST or HOTLINK action.

pFormats must be a pointer to an existing vector in the client program, each
value of which conforms to the rules defined for Format on the ADDFORMAT
action.


ΓòÉΓòÉΓòÉ 113.2.6. EQUALS() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇEQUALS(pLink)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action causes the link to compare itself with the link pointed to by
pLink. If they are equal, then the action returns 1 (true). If not, then it
returns 0 (false).


ΓòÉΓòÉΓòÉ 113.2.7. HOTLINK() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇHOTLINK(Type,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                  ΓööΓöÇFormatΓöÇΓöÿ

This action controls the treatment of the link as a hot link.

Type must be a Boolean value. If it is 1 (true), then whenever the link is
active, the client is told and the server data is updated. This is the default
behavior of a link. If you do not want this behavior, then call the HOTLINK
action with Type set to 0 (false).

Format, if specified, is the format in which the client wishes to receive data
whenever the server is updated. If unspecified, the same rules are used to
determine a format as are described for the REQUEST action.


ΓòÉΓòÉΓòÉ 113.2.8. LOAD() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇLOAD(pObject)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action is used by the application to load link information into the LINK
object. pObject must be a pointer either to a STREAM object provided via ON
TARGET, or to the handle to a CLIPBOARD object where CF_LINK data is available
on the system clipboard.

If there is an active conversation with a server when LOAD is called, the
conversation will be terminated. LOAD effectively replaces the current LINK
definition, and is typically only called once in the life of the LINK.


ΓòÉΓòÉΓòÉ 113.2.9. QUERYFORMATS() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇQUERYFORMATS(pFormats)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action requests the available rendering formats for the linked server. If
NATIVEFORMAT is set, this will always be the first format returned.

pFormats must be a pointer to a vector within the clients program to be
populated with the format information. One format name will be allocated to
each vector element. Any existing data in the vector will be deleted.


ΓòÉΓòÉΓòÉ 113.2.10. REQUEST() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇREQUEST(ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
             ΓööΓöÇFormatΓöÇΓöÿ

This action directs the LINK object to render data from the linked object in
the specified format. Any result of this will be seen by the application
through a TARGET event.

If this action determines that the requested rendering cannot take place, then
ERROR is signaled.

Format, if specified, indicates the format that the rendering will use. If
Format is not specified the format will be:

o DEFAULTFORMAT if it has been set

o The first format specified in the FORMATS or ADDFORMAT actions and known to
  be supported by the server. If there is no match with server formats, the
  first specified format

o The first format specified in the FORMATS item of the SYSTEM topic by the
  server.
If no format can be derived using these rules, an error condition will be
raised.


ΓòÉΓòÉΓòÉ 113.2.11. RESTART() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇRESTART()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action will attempt to restart the server, provided

o The link is not already in DDE conversation with the server,
o The link has usable restart information available.

This information will be obtained from the server using the RESTART item of the
SYSTEM topic. If available, the restart information should be in the form of
the command string that may be passed to DosExecPgm to start the server. LINK
will prefix this string with "START ", and pass the result to the COMMAND
action on the SYSTEM object.

LINK will seek to obtain RESTART information whenever a DDE conversation is
successfully established. If obtained, it will preserved within the link until
the next time a DDE conversation is established with the server.

If RESTART is called while the link is active, or if the link does not have
restart information for the server, an error condition will be raised. If an
error is detected when restarting the server, an error condition will be
raised. However, it is possible that the link may successfully execute a START
command without the server actually starting correctly.


ΓòÉΓòÉΓòÉ 113.2.12. VERIFYFORMAT() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇVERIFYFORMAT(Format)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action requests verification that format is supported by the linked
object. Verification is performed against the currently held format
information.

If the server does not support the FORMATS item of the SYSTEM topic, then no
format information will exist and verification will fail. Nevertheless, the
server may actually support a request for the format, and REQUEST() will not
prevent such a request being made.

This action returns 1 (true) if Format is supported, 0 (false) if Format if not
supported, or NULL if the information needed to determine support is not
available.


ΓòÉΓòÉΓòÉ 113.3. Events ΓòÉΓòÉΓòÉ

ERROR                      QUIT
TARGET(pstream)


ΓòÉΓòÉΓòÉ 113.3.1. ERROR ΓòÉΓòÉΓòÉ

Signaled if REQUEST() determines that rendering cannot take place.


ΓòÉΓòÉΓòÉ 113.3.2. QUIT ΓòÉΓòÉΓòÉ

Signaled when the link requests a shutdown.


ΓòÉΓòÉΓòÉ 113.3.3. TARGET(pstream) ΓòÉΓòÉΓòÉ

This is signaled when data is obtained over the link.


ΓòÉΓòÉΓòÉ 114. LINKSHOW ΓòÉΓòÉΓòÉ

The LINKSHOW object is used by applications to help manage links.

Attributes

Actions

Events

More about LINKSHOW

See also: DDECLIENT, DDESERVER, LINK, SOURCECTRL, TARGETCTRL, REFERENCE


ΓòÉΓòÉΓòÉ 114.1. Attributes ΓòÉΓòÉΓòÉ

OBJECTNAME             LINKS
OWNERWINDOW            VISIBLE


ΓòÉΓòÉΓòÉ 114.1.1. OBJECTNAME ΓòÉΓòÉΓòÉ

This attribute must be a character string of up to 255 bytes. This string is
used to construct the window title of the dialog displayed by LINKSHOW.

Set on OPEN, then read-only.


ΓòÉΓòÉΓòÉ 114.1.2. LINKS ΓòÉΓòÉΓòÉ

This attribute must be a pointer to a vector of pointers to open LINK objects.
Details of each Link will be displayed in the LINKSHOW dialog, and individual
Links may be selected and manipulated.

Set on OPEN, then read-only.


ΓòÉΓòÉΓòÉ 114.1.3. OWNERWINDOW ΓòÉΓòÉΓòÉ

This attribute must be a pointer to a window handle. The referenced window will
be made the OwnerWindow of the LINKSHOW dialog.

Set on OPEN, then read-only.


ΓòÉΓòÉΓòÉ 114.1.4. VISIBLE ΓòÉΓòÉΓòÉ

Setting this Boolean attribute to 1 (true) surfaces the LINKSHOW dialog.


ΓòÉΓòÉΓòÉ 114.2. Actions ΓòÉΓòÉΓòÉ

ADDLINK()


ΓòÉΓòÉΓòÉ 114.2.1. ADDLINK() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇADDLINK(pLink)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action will add a link to the set of links displayed by LINKSHOW. pLink
must be a pointer to an open link.


ΓòÉΓòÉΓòÉ 114.3. Events ΓòÉΓòÉΓòÉ

ERROR             QUIT


ΓòÉΓòÉΓòÉ 114.3.1. ERROR ΓòÉΓòÉΓòÉ

Signaled if an error occurs during processing.


ΓòÉΓòÉΓòÉ 114.3.2. QUIT ΓòÉΓòÉΓòÉ

Signaled when the user closes the LINKSHOW dialog.


ΓòÉΓòÉΓòÉ 114.4. More about LINKSHOW ΓòÉΓòÉΓòÉ

A dialog will be presented by the LINKSHOW object.

The dialog is sizable, and may be maximized but not minimized. The dialog has a
minimum size that will not truncate the push buttons, and will always allow at
least one item to be displayed in the list of Links. If the OWNERWINDOW
attribute of LINKSHOW is set on OPEN, the dialog will behave accordingly.

The main part of the dialog is a three column single selection list box
displaying the APPLICATION, TOPIC, and LINK attribute values of each link known
to LINKSHOW. If there is a fourth column it will contain the, translated, words
Active or Inactive to reflect the status of the corresponding Link. This list
box will resize to match the window size. The remainder of controls are only
enabled as long as there is a link selected, in which case they operate on the
selected link.

The Automatic data update check box may be checked ON to make the link a Hot
link. This means that if the server data changes, the Link will automatically
receive an update which it will forward to its client application. If the link
is not active, automatic data update will come into effect the next time it is
successfully activated.

The Automatic server restart check box may be checked ON to make cause the link
to restart the server if an attempt to activate the link fails. This can only
work if the link has been able to obtain restart information from the server
during a previous conversation. If restart information is not available, this
check box will be disabled in an unchecked state.

The Activate/Deactivate push button will activate or deactivate the link,
depending on the current Link status. Link activation may fail due to the
server not being available, in which case the link will retry activation
automatically every 60 seconds. If automatic server restarting is enabled, an
attempt will be made to restart the server each time activation fails. If
activation succeeds, an active indication will appear as part of the Link
details in the list box, and the text on the button will change from Activate
to Deactivate. If the link subsequently becomes inactive, this indication will
be removed.

The Request push button will request a data rendering from the Link. The client
application will be informed of the data rendering.

The Delete push button will delete the link. The link will be removed from the
list of links.

The Help push button has the standard Help behavior.


ΓòÉΓòÉΓòÉ 115. LIST ΓòÉΓòÉΓòÉ

The LIST object class creates an instance of a list box.

Parent: WINDOW

Attributes

Actions

Events

Examples

More about LIST


ΓòÉΓòÉΓòÉ 115.1. Attributes ΓòÉΓòÉΓòÉ

AUTOREFRESH            BORDER
BGCOLOR                COLTITLE
COLTITLE1              COLTITLE2
COLUMNS                CURSORX
CURSORY                DATAEVENT
ENABLED                EXPRESSION
FIXEDCOLS              FIXEDROWS
FGCOLOR                FONT
FONTTITLE              FONTFIXED
HANDLES                HELP
HORZSCROLL             LEFTCOL
ORDERDATA              ORIGIN
REFERENCE              ROWS
SCROLLEVENT            SELECTCELLS
SELECTCOLS             SELECTMODE
SELECTION              SELECTROWS
SIZEX                  SIZEY
TAGSTYLE               TITLEINFO
TOPROW                 VERTSCROLL
VISIBLE                X
Y


ΓòÉΓòÉΓòÉ 115.1.1. AUTOREFRESH ΓòÉΓòÉΓòÉ

Controls refreshing of list on screen when underlying data is changed.

0         List is not automatically refreshed when underlying data is changed.
          UPDATE, PUT, or REFRESH actions must be used to refresh the list.
1         List is automatically refreshed when a wait state is entered with
          changed data.

Default: 1


ΓòÉΓòÉΓòÉ 115.1.2. BORDER ΓòÉΓòÉΓòÉ

The size of the border around the list box in pixels.

A value of 0 suppresses the border; the maximum value is 29.

Default: 1 (Single pixel border displayed)


ΓòÉΓòÉΓòÉ 115.1.3. BGCOLOR ΓòÉΓòÉΓòÉ

The background color for the list box.

Default: Determined by operating system.


ΓòÉΓòÉΓòÉ 115.1.4. COLTITLE ΓòÉΓòÉΓòÉ

Array of strings, one entry per column. Used as the first line of titles for
the list box if only one title row is specified in FIXEDROWS attribute.
Otherwise, array contains the names of the arrays of titles for each column.
This allows a variable number of title lines to be specified with independent
formatting capabilities (in which case COLTITLE1 and COLTITLE2 attributes are
not required).

The array of titles should correspond in number to the number of columns
specified in REFERENCE.

Default: ""


ΓòÉΓòÉΓòÉ 115.1.5. COLTITLE1 ΓòÉΓòÉΓòÉ

Array of strings, one entry per column. Used as the first line of titles for
the list box.

Default: ""


ΓòÉΓòÉΓòÉ 115.1.6. COLTITLE2 ΓòÉΓòÉΓòÉ

Array of strings, one entry per column. Used as the second line of titles for
the list box.

Default: ""


ΓòÉΓòÉΓòÉ 115.1.7. COLUMNS ΓòÉΓòÉΓòÉ

The number of columns visible in the list box

Read-only.


ΓòÉΓòÉΓòÉ 115.1.8. CURSORX ΓòÉΓòÉΓòÉ

Column number where the edit focus cell is positioned (used with editable list
boxes).

Read-only

Default: None


ΓòÉΓòÉΓòÉ 115.1.9. CURSORY ΓòÉΓòÉΓòÉ

Row number where edit focus cell is positioned (used with editable list boxes).

Read-only

Default: None


ΓòÉΓòÉΓòÉ 115.1.10. DATAEVENT ΓòÉΓòÉΓòÉ

Controls whether the LISTDATA event should be signaled when a locked row is
scrolled out of view, the Ctrl+Enter key is pressed, the Delete key is pressed,
or a column is sized. (See the LISTDATA event.) box is scrolled and updated or
when locked data is moved out of view in an editable list boxes.

0         LISTDATA event is not signaled
1         LISTDATA event is signaled

Default: 0


ΓòÉΓòÉΓòÉ 115.1.11. ENABLED ΓòÉΓòÉΓòÉ

Whether the list box is enabled:

0         List box disabled-data cannot be selected or scrolled
1         List box enabled-data can be selected or scrolled but not updated.
2         List box enabled-data can be selected, scrolled, and updated.
3         List box enabled-data can be selected, scrolled and columns can be
          resized (but not updated).
4         List box enabled-data can be selected, scrolled, updated and columns
          can be resized.

Default: 1 (Enabled for read-only)


ΓòÉΓòÉΓòÉ 115.1.12. EXPRESSION ΓòÉΓòÉΓòÉ

Array of strings, one for each column, defining how the columns should be
displayed.

Each string, which must be enclosed in quotation marks ("), can contain the
following parts, separated by a space:

FGCOLOR=  Foreground color to be displayed for that column.

          Default: 0 (Default foreground color for column display)

BGCOLOR=  Background color to be displayed for that column.

          Default: 0 (Default background color for column display)

LENGTH=   Maximum data width in characters (only used with editable list
          boxes). Default: 255

READONLY= YES or NO. Default: NO (If ENABLED is set, data can be edited)

UNDERLINE= YES or NO. Default: NO

WIDTH=    Column width in dialog units. Default: 0

SEPARATOR= YES or NO. Default: NO

JUST=     LEFT, RIGHT, or CENTER. Default: LEFT

Keywords may be in any order, but each keyword must be separated by at least
one blank. No blanks are allowed before or after the equal sign ( =).

Set on OPEN, then read-only.


ΓòÉΓòÉΓòÉ 115.1.13. FIXEDCOLS ΓòÉΓòÉΓòÉ

FIXEDCOLS is the number of columns to be fixed at the left side in the list
box. If too large a value is supplied, the number of columns will be used
instead.

Default: 0 (No fixed columns)


ΓòÉΓòÉΓòÉ 115.1.14. FIXEDROWS ΓòÉΓòÉΓòÉ

This is the number of fixed title rows for each column.

FIXEDROWS must be less than or equal to the total number of rows. If COLTITLE1
(or COLTITLE2) array has been supplied, excess fixed rows will be padded out
with blank entries. (For example, if COLTITLE1 and COLTITLE2 are used to
specify titles but FIXEDROWS=4, two blank title rows will be inserted after the
specified title.)

Default: 0 (No title rows)


ΓòÉΓòÉΓòÉ 115.1.15. FGCOLOR ΓòÉΓòÉΓòÉ

The color for the border.

Default: Determined by operating system.


ΓòÉΓòÉΓòÉ 115.1.16. FONT ΓòÉΓòÉΓòÉ

The font for the main area.

Acceptable values are displayed in the OS/2 Font Palette.

Default: Determined by operating system.


ΓòÉΓòÉΓòÉ 115.1.17. FONTTITLE ΓòÉΓòÉΓòÉ

The font for the TITLE row (or rows).

Acceptable values are displayed in the OS/2 Font Palette.

Default: Determined by operating system.


ΓòÉΓòÉΓòÉ 115.1.18. FONTFIXED ΓòÉΓòÉΓòÉ

The font for the fixed column (or columns).

Acceptable values are displayed in the OS/2 Font Palette.

Default: Determined by operating system.


ΓòÉΓòÉΓòÉ 115.1.19. HANDLES ΓòÉΓòÉΓòÉ

Whether sizing handles are attached to the list box to support moving, sizing,
and copying operations. These direct manipulation techniques follow the CUA
guidelines. See also the AUTOSELECT attribute of the WINDOW object.

0         Handles are not displayed
1         Handles are displayed

Default: 0 (No handles)


ΓòÉΓòÉΓòÉ 115.1.20. HELP ΓòÉΓòÉΓòÉ

Resource identifier (res ID) of the help text for this object.

Default: 0


ΓòÉΓòÉΓòÉ 115.1.21. HORZSCROLL ΓòÉΓòÉΓòÉ

Horizontal scroll bar drawn to enable data scrolling:

0         No horizontal scroll bar drawn
1         Horizontal scroll bar drawn, scrolling by pixel
2         Horizontal scroll bar drawn, scrolling by column

Set on OPEN, then read-only.

Default: 0 (No horizontal scroll bar)


ΓòÉΓòÉΓòÉ 115.1.22. LEFTCOL ΓòÉΓòÉΓòÉ

Column currently displayed at the left of the list. The value must be equal to
or greater than the first nonfixed column and less than or equal to the total
number of columns. If the value is greater than the first nonfixed column, it
will be replaced by the value for that column.

Default: 1


ΓòÉΓòÉΓòÉ 115.1.23. ORDERDATA ΓòÉΓòÉΓòÉ

Array containing the row numbers of the data to be loaded into the list box.
array can be used to load the list box with a subset of the data or to reorder
the rows (or a combination of both).

The row numbers in array can be changed after the list has been opened. The new
rows will be displayed if AUTOREFRESH is on, or REFRESH() is called.

Default: None, all rows are displayed.


ΓòÉΓòÉΓòÉ 115.1.24. ORIGIN ΓòÉΓòÉΓòÉ

The corner of the enclosing window to be taken as the origin.  The position of
the list box is measured from this point.

"TL"      Top left
"TR"      Top right
"BL"      Bottom left
"BR"      Bottom right

Default: "BL" (Bottom left)


ΓòÉΓòÉΓòÉ 115.1.25. PACKET ΓòÉΓòÉΓòÉ

Data reading by packets of rows enabled or disabled: Reading by data packets is
useful when displaying large amounts of data.

0         Data packets are not used
1         Data packets are used

Default: 0 (Set on OPEN then read-only)


ΓòÉΓòÉΓòÉ 115.1.26. REFERENCE ΓòÉΓòÉΓòÉ

Array containing the names of the arrays that contain each column of data.

Do not change the value of REFERENCE in order to change the data that the LIST
object references. To change the referenced data, first close the LIST object.
Then open it with a new value of REFERENCE and a corresponding new value of
EXPRESSION. You can change the referenced data, for example, to change the
number of columns that the list box shows.

Default: ""


ΓòÉΓòÉΓòÉ 115.1.27. ROWS ΓòÉΓòÉΓòÉ

The number of rows visible in the list box

Read-only.


ΓòÉΓòÉΓòÉ 115.1.28. SCROLLEVENT ΓòÉΓòÉΓòÉ

Determines whether the LISTSCROLL event will be signaled when the list box is
scrolled.

0         LISTSCROLL event is not signaled when scrolling occurs.
1         LISTSCROLL event is signaled when scrolling occurs

Default: 0


ΓòÉΓòÉΓòÉ 115.1.29. SELECTCELLS ΓòÉΓòÉΓòÉ

Enables selection of cells in the list box: Cells can be selectable with or
without having selection tags. Except for one-select list boxes (where one item
cannot be deselected without selecting a new item), the user will only be able
to select those cells with selection tags.

0         No cells can be selected
1         Cells can be selected, but have no tags
2         Cells can be selected, and have tags

Set on OPEN, then read-only.

Default: 0 (No cells can be selected)


ΓòÉΓòÉΓòÉ 115.1.30. SELECTCOLS ΓòÉΓòÉΓòÉ

Enables selection and editing of fixed and scrollable columns in the list box:
Selection of fixed and scrollable columns can be independently controlled.
(Selection tags can be shown for scrollable columns only or for both selectable
and fixed columns.)

When a list is editable (except for one-select list boxes), the user will only
be able to select those columns that have selection tags.

Values in a list box can be edited if ENABLED is set appropriately. (Columns
may also be affected by the READONLY part of the EXPRESSION attribute.)

0         No selection. If the list is editable, only scrollable columns can be
          edited.
1         Columns selectable, no tags. Only scrollable columns can be selected,
          but the columns have no tags. If the list is editable, only
          scrollable columns can be edited.
2         All columns can be selected. Scrollable columns have tags. If the
          list is editable, all columns can be edited.
3         All columns can be selected. No columns have tags. If the list is
          editable, all columns can be edited.
4         All columns can be selected. All columns have tags. If the list is
          editable, all columns can be edited.

Set on OPEN, then read-only.

Default: 0 (No selection)


ΓòÉΓòÉΓòÉ 115.1.31. SELECTMODE ΓòÉΓòÉΓòÉ

Current selection type:

0         No selections have been made.
1         Row. One or more rows have been selected
2         Column. One or more columns have been selected
3         Row/Column. One or more rows and columns have been selected
4         Cell. One or more cells have been selected
5         Row/Cell. One or more rows and cells have been selected
6         Column/Cell. One or more columns and cells have been selected
7         Row/Column/Cell. One or more rows, columns and cells have been
          selected.

Set when item selected, then read-only. QUERYCHECK can be used to determine
which rows, columns, or cells have been selected.

Default: None


ΓòÉΓòÉΓòÉ 115.1.32. SELECTION ΓòÉΓòÉΓòÉ

Selection type from the list box:

0         Extended selection. More than one item can be selected (by striping
          or extended selection from the keyboard).
1         Single selection. Only one item can be selected
2         Multiple selection. More than one item can be selected (subsequent
          selections are added to the existing selections)
3         List is enabled but not selectable (except under program control).
4         One selection. Deselection cannot be done without selecting another
          item.

Set on OPEN, then read-only.

Default: 0 (Extended selection)


ΓòÉΓòÉΓòÉ 115.1.33. SELECTROWS ΓòÉΓòÉΓòÉ

Enables selection and editing of fixed and scrollable rows in the list box.
Selection of fixed (title) and scrollable rows can be independently controlled.
(Selection tags can be shown for scrollable rows only or for both fixed and
scrollable rows.)

When a list is editable (except for one-select list boxes), the user will only
be able to select those rows that have selection tags.

Values in a list box can be edited if ENABLED is set appropriately. (title rows
may be affected by the READONLY part of the TITLEINFO attribute as well.)

0         No selection. This setting has no effect if SELECTCOLS and
          SELECTCELLS are also zero. To turn off all selection capability, use
          the SELECTION attribute. If the list is editable, only scrollable
          rows can be edited.
1         Only scrollable rows can be selected (but there are no row tags). If
          the list is editable, only scrollable rows can be edited.
2         Only scrollable rows can be selected (there are row tags). If the
          list is editable, all rows can be edited.
3         All rows can be selected (but no rows have tags). If the list is
          editable, all rows can be edited.
4         All rows can be selected (and all rows have tags). If the list is
          editable, all rows can be edited.

Set on OPEN, then read-only.

Default: 1 (Rows selectable but no tags)


ΓòÉΓòÉΓòÉ 115.1.34. SIZEX ΓòÉΓòÉΓòÉ

Width, in dialog units.

Default: 0


ΓòÉΓòÉΓòÉ 115.1.35. SIZEY ΓòÉΓòÉΓòÉ

Height, in dialog units.

Default: 0


ΓòÉΓòÉΓòÉ 115.1.36. TAGSTYLE ΓòÉΓòÉΓòÉ

This specifies the style of tags to be displayed when tags have been specified
in SELECTROWS, SELECTCOLS, or SELECTCELLS attributes. (All tags in the display
will be of the same type.)

0         Marker style tags
1         Hidden tags
2         Button style tags

          Default: 0 (Marker tags)


ΓòÉΓòÉΓòÉ 115.1.37. TITLEINFO ΓòÉΓòÉΓòÉ

Array of strings, one for each column, defining how the column title rows
should be displayed. The WIDTH of the title column is not required since the
width of the column of data to be displayed underneath the title is used.

Each string, which must be enclosed in quotation marks ("), can contain the
following parts, separated by a comma:

LENGTH=   Maximum data width in characters.

          Default: 255 This is only used with editable titles.

SEPARATOR= YES or NO

          Default: NO

UNDERLINE= YES or NO

          Default: NO

JUST=     LEFT, RIGHT or CENTER Default is LEFT.

READONLY= YES or NO

          Default: NO The title is editable if ENABLED is set.

FGCOLOR=  Foreground color to be displayed for that column.

          Default: 0 (Default foreground color for column display)

BGCOLOR=  Background color to be displayed for that column

          Default: 0 (Default background color for column display)

Keywords may be in any order separated by at least one blank. No blanks are
allowed before or after the = sign.

Set on OPEN, then read-only.


ΓòÉΓòÉΓòÉ 115.1.38. TOPROW ΓòÉΓòÉΓòÉ

Row to be displayed (or currently displayed) at the top of the list.

Default: 1


ΓòÉΓòÉΓòÉ 115.1.39. VERTSCROLL ΓòÉΓòÉΓòÉ

Vertical scroll bar drawn to enable data scrolling:

0         No vertical scroll bar drawn
1         Vertical scroll bar drawn

Set on OPEN, then read-only.

Default: 1 (Vertical scroll bar)


ΓòÉΓòÉΓòÉ 115.1.40. VISIBLE ΓòÉΓòÉΓòÉ

Whether the list is displayed:

0         List box not displayed
1         List box displayed

Default: 1 (Displayed)


ΓòÉΓòÉΓòÉ 115.1.41. X ΓòÉΓòÉΓòÉ

Horizontal position of the bottom left-hand corner of the list, in dialog
units.

Default: 0


ΓòÉΓòÉΓòÉ 115.1.42. Y ΓòÉΓòÉΓòÉ

Vertical position of the bottom left-hand corner of the list, in dialog units.

Default: 0


ΓòÉΓòÉΓòÉ 115.2. Actions ΓòÉΓòÉΓòÉ

CHECK()                  CREATE()
CURSORBOX()              DESTROY()
EDIT()                   GET()
GETROW()                 GETTITLE()
LOCK()                   PLACECURSOR()
PUT()                    PUTTITLE()
QUERYCHECK()             QUERYCURSOR()
QUERYLOCKED()            QUERYWIDTH()
REFRESH()                SETCHECK()
SETCOLOR()               SETWIDTH
UNCHECK()                UNLOCK()
UPDATE()


ΓòÉΓòÉΓòÉ 115.2.1. CHECK() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇCHECK(ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
           ΓööΓöÇrow_numberΓöÇΓöÿ   ΓööΓöÇcolumn_numberΓöÇΓöÿ

Marks a row, column, or cell as selected. For lists where only one item can be
selected, this turns off any other selections. For lists where more than one
item can be selected, this is in addition to any existing selections. (To
select a cell, specify both column_number and row_number.) If  column_number or
row_number is zero, all selections are removed.


ΓòÉΓòÉΓòÉ 115.2.2. CREATE() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇCREATE(array,row_number)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Inserts a new row at position  row_number, putting there the contents of the
variable array (one entry per column). The list box will return the next
available insert row number. When a created row is selected, A.System.BoxNumber
is set to the value returned by the CREATE action and A.System.BoxValue is set
to "INSERTED".

The created row can be locked (using the LOCK action) so that a LISTDATA event
is signaled whenever it is scrolled out of view. If the ORDERDATA attribute is
used, the program should update the the ORDERDATA vector when rows are inserted
into the list with CREATE().


ΓòÉΓòÉΓòÉ 115.2.3. CURSORBOX() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇCURSORBOX(row_number,column_number)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Repositions the top left corner of the list box to the specified row number,
and from the indicated column.

The values must be valid row and column numbers.


ΓòÉΓòÉΓòÉ 115.2.4. DESTROY() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇDESTROY(row_number)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Deletes the list box row at the given row_number. This action should only be
called after the corresponding data has been deleted, except when deleting a
row inserted by CREATE().

If the ORDERDATA attribute is used, the program should update the ORDERDATA
vector when rows are deleted from the data or list box.


ΓòÉΓòÉΓòÉ 115.2.5. EDIT() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇEDIT(argument)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Enables the programmer to query whether a clipboard operation is supported and,
if it is, to carry it out.

argument is a clipboard query or a clipboard operation.

The following values for argument are used to check whether particular
clipboard operations can be supported with the list box in its current state:

"Querycut" Cut to clipboard
"Querycopy" Copy to clipboard
"Querypaste" Paste from clipboard
"Queryclear" Clear clipboard.

Where clipboard operations are supported, the following values for argument
direct them to be carried out:

"Cut"     Cut to clipboard
"Copy"    Copy to clipboard
"Paste"   Paste from clipboard
"Clear"   Clear clipboard.
Clipboard operations are only performed by the list on data in an edit cell.


ΓòÉΓòÉΓòÉ 115.2.6. GET() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇGET(ret_value,row_number,column_number)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Returns value of specified list box cell in ret_value.

The values must be valid row and column numbers.


ΓòÉΓòÉΓòÉ 115.2.7. GETROW() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇGETROW(array,row_number)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Allows retrieval of all the values for any row in the list box. All changes
made to the data in the list box will be retrieved.

array is an array which will be filled up from the list box. Each element of
the array corresponds to a column in the list box.

row_number is the list box row number from which the data is to be retrieved.

The value must be a valid row number and the array must exist.


ΓòÉΓòÉΓòÉ 115.2.8. GETTITLE() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇGETTITLE(ret_value,row_number,column_number)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Returns value of the specified title in ret_value.

The values must be valid row and column numbers for titles.


ΓòÉΓòÉΓòÉ 115.2.9. LOCK() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇLOCK(row_number)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Marks a row as locked. This is in addition to any existing locked rows.

The value must be a valid row number. Rows are automatically locked in an
editable list box when values are changed by the user. For more information on
locking, see the DATA and LISTDATA events.


ΓòÉΓòÉΓòÉ 115.2.10. PLACECURSOR() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇPLACECURSOR(row_num,col_num,start_pos,length)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Places cursor at start position start_pos and highlights the number of bytes
specified in length in the cell of the list box at the row and column specified
in row_num and col_num.

The values must be valid row and column numbers.


ΓòÉΓòÉΓòÉ 115.2.11. PUT() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇPUT(new_value,row_number,column_number)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Updates the value of the cell in the list box.

The values must be valid row and column numbers.


ΓòÉΓòÉΓòÉ 115.2.12. PUTTITLE() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇPUTTITLE(new_value,row_number,column_number)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Updates the value of the specified title in the list box.

The values must be valid row and column numbers for titles.


ΓòÉΓòÉΓòÉ 115.2.13. QUERYCHECK() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇQUERYCHECK(ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                ΓööΓöÇrow_arrayΓöÇΓöÿ   ΓööΓöÇcolumn_arrayΓöÇΓöÿ

Returns a list of the currently selected rows, columns, or cells. If  row_array
only is specified, it is filled with the row numbers of the currently selected
rows. If  column_array only is specified, it is filled with the column numbers
of the currently selected columns. If both are specified, they are filled with
the row and column numbers of the currently selected cells.

row_array or column_array must already exist.


ΓòÉΓòÉΓòÉ 115.2.14. QUERYCURSOR() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇQUERYCURSOR(start_position,length)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Returns (in start_position and length) the start position of the cursor and
length of highlighted text (if the cursor is in edit mode within a cell). The
values returned indicate the number of bytes.


ΓòÉΓòÉΓòÉ 115.2.15. QUERYLOCKED() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇQUERYLOCKED(array)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Fills array with the row numbers of any items that have been marked as locked.
array must already exist. For more information, see the DATA and LISTDATA
events.


ΓòÉΓòÉΓòÉ 115.2.16. QUERYWIDTH() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇQUERYWIDTHΓöÇΓöÇ(ΓöÇΓöÇcolumn_numberΓöÇΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Returns the width (in dialog units) of the column specified by column_number.


ΓòÉΓòÉΓòÉ 115.2.17. REFRESH() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇREFRESH()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Forces repainting of the list box on the screen. When AUTOREFRESH is off, use
REFRESH() to make the list box read new values from the underlying data.


ΓòÉΓòÉΓòÉ 115.2.18. SETCHECK() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSETCHECK(ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
              ΓööΓöÇrow_arrayΓöÇΓöÿ   ΓööΓöÇcolumn_arrayΓöÇΓöÿ

Selects rows, columns, or cells in the list. If only  row_array is supplied,
rows are selected. If only  column_array is supplied, columns are selected.

Cells are selected if both row_array and column_array are used. All existing
selections are turned off first.


ΓòÉΓòÉΓòÉ 115.2.19. SETCOLOR() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSETCOLORΓöÇΓöÇ(ΓöÇΓöÇrowΓöÇΓöÇ,ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇ,ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                         ΓööΓöÇforegroundΓöÇΓöÿ     ΓööΓöÇbackgroundΓöÇΓöÿ

Sets the foreground color, or the background color, or both, for the row number
specified in row.


ΓòÉΓòÉΓòÉ 115.2.20. SETWIDTH ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSETWIDTHΓöÇΓöÇ(ΓöÇΓöÇcolumn_number,widthΓöÇΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Sets the width (in dialog units) of the column specified by column_number to
width.


ΓòÉΓòÉΓòÉ 115.2.21. UNCHECK() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇUNCHECK(ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
             ΓööΓöÇrow_numberΓöÇΓöÿ   ΓööΓöÇcolumn_numberΓöÇΓöÿ

Deselects a row when  row_number is used alone to indicate a valid row number.

Deselects a column when  column_number is used alone to indicate a valid column
number.

Deselects a cell when both row_number and column_number are used.


ΓòÉΓòÉΓòÉ 115.2.22. UNLOCK() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇUNLOCK(row_number)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Releases the lock on the specified row allowing a fresh copy of the data to be
read from the columns referred to in REFERENCE. UNLOCK is used to inform the
list box that updated values in the row have been written to the underlying
data and that the row can now be scrolled out of view without the need for a
LISTDATA event. For more information, see the DATA and LISTDATA events. Rows
are automatically unlocked when the REFRESH() action is called.

The value must be a valid row number.


ΓòÉΓòÉΓòÉ 115.2.23. UPDATE() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇUPDATE(array,row_number)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Allows selective updating of a row of a list box. This is useful with large
lists where a full REFRESH would take an unacceptably long time.

Only the screen display is updated. The underlying data is not altered, and is
redisplayed when REFRESH is called (or when a new packet of data is loaded into
the list if PACKET is on). The program should also update the data when UPDATE
is used (or LOCK can be used to prevent the new values being lost when
scrolling causes fresh packets of data to be read).

array is an array containing the values to be inserted in the list box. Each
element of the array is a column in the list box.

row_number corresponds to the row position at which the values contained in
array are to be updated.


ΓòÉΓòÉΓòÉ 115.3. Events ΓòÉΓòÉΓòÉ

DATA                  DESKTOP
ESCAPE                HELP
LISTDATA              LISTSCROLL
OPEN                  SELECT


ΓòÉΓòÉΓòÉ 115.3.1. DATA ΓòÉΓòÉΓòÉ

Signaled when data has changed within the list box cell and the TAB key is
pressed or another object is selected.

A.System.Object is set to the name of the list box. A.System.BoxValue is set to
the new value of the changed cell. A.System.PositionX is set to the column
number of the changed cell.

A.System.PositionX, A.System.PositionY, A.System.Boxnumber, and
A.System.Operation are used to identify the changed cell:

o If the changed cell was in a title row, A.System.PositionY is set to the
  title row number and A.System.Operation is set to "TITLE".

o If the changed cell was in an inserted row, A.System.PositionY is set to the
  list box number of the changed cell, A.System.BoxNumber is set to the
  inserted row number (returned by the CREATE action) and A.System.Operation is
  set to "INSERTED".

o Otherwise, A.System.PositionY is set to the list box number of the changed
  cell and A.System.BoxNumber is set to the row number of the data within the
  columns or vectors specified using the REFERENCE attribute.

Normally A.System.PositionY and A.System.BoxNumber differ only if CREATE() has
been used to insert rows earlier in the list or if the ORDERDATA attribute has
been used to specify which rows of data should be displayed in the list.

If an editable list box is displaying only rows 11 to 50 of a table and a value
is changed in a cell in row 3 for example, A.System.PositionY will be set to 3
and and A.System.BoxNumber will be set to 13.


ΓòÉΓòÉΓòÉ 115.3.2. DESKTOP ΓòÉΓòÉΓòÉ

Signaled when the list box is moved, sized, or copied. A.System.Operation is
set to "MOVE", "SIZE", or "COPY". A.System.Object contains the name of the
control.


ΓòÉΓòÉΓòÉ 115.3.3. ESCAPE ΓòÉΓòÉΓòÉ

Signaled when the user presses the ESCAPE key.

A.System.Object is set to the name of the list box.


ΓòÉΓòÉΓòÉ 115.3.4. HELP ΓòÉΓòÉΓòÉ

Signaled when the user presses the F1 key in any area within the list box
(unless the HELP attribute is set).

A.System.Object is set to the name of the list box.


ΓòÉΓòÉΓòÉ 115.3.5. LISTDATA ΓòÉΓòÉΓòÉ

Signaled if DATAEVENT is on and one of the following conditions has occurred:

 1. One or more locked rows have been scrolled out of view in the list box.
    (rows are locked when values are changed by the user in an editable list or
    by using the LOCK action). A.System.Operation is set to "SCROLL".
 2. The CTRL ENTER key has been pressed while the focus is in the list. This
    can be used as a signal for a new row to be inserted, by CREATE, at the
    selection point. A.System.Operation is set to "INSERT".
 3. The DELETE key has been pressed while the focus is in the list, (this can
    be used as a signal for the selected item to be deleted).
    A.System.Operation is set to "DELETE".
 4. A column divider has been moved in a list box where column widths can be
    changed (see the ENABLED attribute). A.System.Operation is set to "WIDTH".

If the user changes a value in a row of an editable list box and attempts to
scroll the value off the screen (without tabbing out of the cell), a LISTDATA
event will occur. The DATA event informing the program of the change will not
yet have occurred at this point. The program can call the FLUSH action of the
window, to force a DATA event, and then use the GET action of the list to find
the newly typed value.

A.System.Object is set to the name of the list box.

When an INSERT or DELETE operation is signaled, then A.System.PositionX,
A.System.PositionY, A.System.BoxValue, and A.System.Boxnumber are used to
identify the current list box item (row, column, or cell).

A.System.PositionX is set to the column number of the current item (or is set
to zero if it is a row).

o If the current item is in a title row, then A.System.PositionY is set to the
  title row number. A.System.BoxValue is set to "TITLE".

o If the current item is in an inserted row, then A.System.PositionY is set to
  the list box row number of the current item, A.System.BoxNumber is set to the
  inserted row number of the selected item (returned by the CREATE() action),
  and A.System.BoxValue is set to "INSERTED".

o Otherwise, A.System.PositionY is set to the list box number of the current
  item (or zero if it is a column) and A.System.BoxNumber is set to the row
  number of the underlying data for the row (or zero if the current item is a
  column).

When a WIDTH operation is signaled, A.System.PositionX is set to the column
number of the resized column and A.System.BoxNumber is set to the new column
width in dialog units.


ΓòÉΓòÉΓòÉ 115.3.6. LISTSCROLL ΓòÉΓòÉΓòÉ

Signaled when SCROLLEVENT is on and the list box is scrolled.

A.System.Object is set to the name of the list box. A.System.Operation is set
to "HSCROLL" for a horizontal scroll or "VSCROLL" for a vertical scroll.
A.System.PositionX is set to the new LEFTCOL column number. A.System.PositionY
is set to the new TOPROW row number.

A.System.Boxnumber and A.System.BoxValue are set to the data row number and
data row type of the new top row using the same values as described above for
the INSERT and DELETE operations in the LISTDATA event.


ΓòÉΓòÉΓòÉ 115.3.7. OPEN ΓòÉΓòÉΓòÉ

Signaled when a list box item is double-clicked (or if ENTER is pressed within
the list). A.System.Object is set to the name of the list box.
A.System.Operation is set to the SELECTMODE number of the selected item (1 for
a row, 2 for a column, or 4 for a cell).

A.System.PositionX, A.System.PositionY, A.System.Boxnumber and
A.System.BoxValue are used to identify the selected list box item using the
same values as described above for the INSERT and DELETE operations in the
LISTDATA event.


ΓòÉΓòÉΓòÉ 115.3.8. SELECT ΓòÉΓòÉΓòÉ

Signaled when a list box item is selected. A.System.Object is set to the name
of the list box. A.System.Operation is set to the SELECTMODE number of the
selected item (1 for a row, 2 for a column, or 4 for a cell).

A.System.PositionX, A.System.PositionY, A.System.Boxnumber, and
A.System.BoxValue are used to identify the last selected item of the type
specified by A.System.Operation (or the current selection if there is only one)
using the same values as described above for the INSERT and DELETE operations
in the LISTDATA event.

If the last item was deselected, A.System.PositionX, A.System.PositionY, and
A.System.Boxnumber will be zero.


ΓòÉΓòÉΓòÉ 115.4. Examples ΓòÉΓòÉΓòÉ

!
! First we set up some vectors of data to display in the list.
!
DEFINE array1[0]
INSERT array1[0] = "January"
INSERT array1[0] = "February"
...
INSERT array1[0] = "December"

DEFINE array2[0]
INSERT array2[0] = "Jan"
INSERT array2[0] = "Feb"
...
INSERT array2[0] = "Dec"
!
! We have to set up some arrays to support the list object.
! Corresponding elements of the arrays refer to the same list column
!
! The EXPRESSION array defines the columns to be displayed,
! in this case two equal columns, with separators, left justified.
!
DEFINE listexpr[0]
INSERT listexpr[0] = "WIDTH=100 SEPARATOR=yes JUST=left"
INSERT listexpr[0] = "WIDTH=100 SEPARATOR=yes JUST=left"

!
! The REFERENCE array lists the vectors to be displayed in the columns,
! identified by data manager name (DECLAREd vectors can't be used)
!
DEFINE listref[0]
INSERT listref[0] = array1[0]   /* by dictionary */
INSERT listref[0] = "array2"    /* by name       */

!
! The COLTITLE1 attribute takes an array holding the titles for the
! columns. Titles are optional, and there may be two rows (in which
! case a second array can be supplied to the ! COLTITLE2 attribute).
!
DEFINE listtitle[0]
INSERT listtitle[0] = "Long month"
INSERT listtitle[0] = "Short month"

This example opens a list box in single select mode.

!
! Now we're ready to open the LIST object
!
OPEN LIST list1, MyWin,
 X = 8, Y = 6,
 SIZEX = 180, SIZEY = 70,
 ORIGIN = "BL",
 VISIBLE = 1,
 HORZSCROLL = 1, VERTSCROLL = 1,
 BORDER = 1,
 ENABLED = 1,
 SELECTION = 1,
 EXPRESSION = listexpr[0],
 REFERENCE = listref[0],
 COLTITLE1 = listtitle[0],
 TOPROW = 5   /* put row 5 at the top of the list */
!
! as an example, preselect the 7th row (which is the 3rd displayed row)
!
CALL t..list1'CHECK(7)

This example opens a list box in extended select mode.

!
! The EXPRESSION array
DEFINE listexpr[0]
INSERT listexpr[0] = "WIDTH=80 SEPARATOR=yes JUST=right"
INSERT listexpr[0] = "WIDTH=120 SEPARATOR=yes JUST=left"
!
! The REFERENCE array
DEFINE listref[0]
INSERT listref[0] = "attrs"
INSERT listref[0] = "values"
!
! The COLTITLE1 array for titles
DEFINE listtitle[0]
INSERT listtitle[0] = "Profile attribute"
INSERT listtitle[0] = "Current contents"
!
! A TITLEINFO array to define how the titles appear
DEFINE listtitleinfo[0]
INSERT listtitleinfo[0] = "SEPARATOR=yes JUST=right"
INSERT listtitleinfo[0] = "SEPARATOR=yes JUST=left"
!
OPEN LIST list2, MyWin2,
 X = 8, Y = 6,
 SIZEX = 180, SIZEY = 70,
 ORIGIN = "BL",
 VISIBLE = 1,
 HORZSCROLL = 1, VERTSCROLL = 1,
 BORDER = 1,
 ENABLED = 1,
 SELECTION = 0,
 REFERENCE = listref[0],
 EXPRESSION = listexpr[0],
 COLTITLE1 = listtitle[0],
 TITLEINFO = listtitleinfo[0]
!
! as an example, preselect rows 1,3 & 5
!
DEFINE cursel[0]
INSERT cursel[1]=1
INSERT cursel[2]=3
INSERT cursel[3]=5
CALL t..list2'SETCHECK(cursel[0])
!
! uncheck the third row
!
CALL t..list2'UNCHECK(3)
!
! fill a vector with items currently selected
!
DEFINE cursel[0]
CALL t..list2'QUERYCHECK(cursel[0])
!
! 'cursel' now contains { 1, 5 }
!

The list box can be resized to fit the window.  The following code is placed
into the ON DESKTOP block to handle sizing requests on the window holding the
list box.

ON DESKTOP
DO
  IF A.System.Object = POINTER(MyWin2[0]) &
     A.System.Operation = "SIZE"
  THEN DO
    MODIFY list2,
     SIZEX = MyWin2'SIZEX - 16,
     SIZEY = MyWin2'SIZEY - 15
    ...

Examples source library:


ΓòÉΓòÉΓòÉ 115.5. More about LIST ΓòÉΓòÉΓòÉ

o The LIST object cannot be cloned.

o The maximum number of rows which may be displayed is 64000.

o A DATA event is signaled each time data in any of the cells is amended in any
  way, and a lock is put on that row inhibiting any rereading of the column
  data for that row from any of the REFERENCE columns.

o The program should update the underlying data for the changed cell and call
  UNLOCK() to unlock the row.

o A HELP event is signaled if help is requested while editing in the list box.
  The CURSORX and CURSORY attributes will return the focus position so that
  appropriate contextual help can be provided by the application.


ΓòÉΓòÉΓòÉ 116. LOCATION() ΓòÉΓòÉΓòÉ

The LOCATION() function returns the file location from the name.

ΓöÇΓöÇLOCATION(name)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Examples

More about LOCATION()

See also: FULLPATH(), NAME()


ΓòÉΓòÉΓòÉ 116.1. Examples ΓòÉΓòÉΓòÉ

LET filelocn = LOCATION(os2file)
LET filename = NAME(os2file)

ON START(parms, filespec)           /* ON START for the key program     */
DO
  DECLARE CHAR[*] parms
  DECLARE CHAR[*] filespec

  OPEN FILE datafile,
   NAME = "proginfo.dat",           /* look for data file in the same   */
   LOCATION = LOCATION(filespec)    /* directory as our App objectstore */

Examples source library:


ΓòÉΓòÉΓòÉ 116.2. More about LOCATION() ΓòÉΓòÉΓòÉ

o You can use LOCATION() with a DBCS name.


ΓòÉΓòÉΓòÉ 117. LOG() ΓòÉΓòÉΓòÉ

The LOG() function returns the logarithm of a value, to a specified base.

ΓöÇΓöÇLOG(ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇexpression)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
         ΓööΓöÇbase,ΓöÇΓöÿ

Examples

More about LOG()


ΓòÉΓòÉΓòÉ 117.1. Examples ΓòÉΓòÉΓòÉ

LET x = LOG(10,38)                    !  Result is 1.58
LET y = LOG(3.142)                    !  Result is 1.14

Examples source library:


ΓòÉΓòÉΓòÉ 117.2. More about LOG() ΓòÉΓòÉΓòÉ

o An error occurs if expression is nonnumeric, is less than or equal to 0, or
  is greater than 10**28.


ΓòÉΓòÉΓòÉ 118. MAIL ΓòÉΓòÉΓòÉ

The MAIL object provides the ability to send objects or files to other
applications using a mail system, such as cc:Mail.

Attributes

Actions

Events: None.

Examples


ΓòÉΓòÉΓòÉ 118.1. Attributes ΓòÉΓòÉΓòÉ

CODE


ΓòÉΓòÉΓòÉ 118.1.1. CODE ΓòÉΓòÉΓòÉ

The error code from the most recent MAIL action.

Default: 0 (No error)


ΓòÉΓòÉΓòÉ 118.2. Actions ΓòÉΓòÉΓòÉ

SEND()               SMISEND()


ΓòÉΓòÉΓòÉ 118.2.1. SEND() ΓòÉΓòÉΓòÉ

                                ΓöîΓöÇ0ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöÇΓöÇSEND(names,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ,ΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                ΓööΓöÇlocationsΓöÇΓöÿ   ΓööΓöÇdeleteΓöÇΓöÿ

This action interfaces with a mail system. It provides a dialog that allows the
user to specify details such as recipients and subject. Then it calls the mail
system API.

names is a scalar or vector. Each element contains the name of a file to be
mailed.

locations is a vector or scalar. Each element specifies the location of the
file named in the corresponding element of names. If locations is omitted, the
MAIL directory in FTB1DIR is assumed.

delete is a flag. If it is set to 1 (true), then the files are deleted when the
call to the mail system is complete.


ΓòÉΓòÉΓòÉ 118.2.2. SMISEND() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSMISEND(to,file,location,subject,message)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action sends mail without using the mail system end-user interface.

to is a scalar that specifies the message recipient.

file is a scalar that specifies the name of a file to be sent.

location is a scalar that specifies the location of file.

subject is a scalar that specifies the subject of the message.

message is a scalar that specifies the message text.


ΓòÉΓòÉΓòÉ 118.3. Examples ΓòÉΓòÉΓòÉ

The following example shows how to mail two files from the directory named
CHARTS.

DEFINE names[2]
DEFINE locns[2] = 'D:\CHARTS'
LET names[1] = 'CHARTEMP'
LET names[2] = 'CHARTEMP.MET'
CALL MyMail'SEND(names[0], locns[0])

Examples source library:


ΓòÉΓòÉΓòÉ 119. MAX() ΓòÉΓòÉΓòÉ

The MAX() function returns the maximum value of a series of values.

         <ΓöÇ,ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöÇΓöÇMAX(ΓöÇΓöÇΓöÇexpressionΓöÇΓö┤ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Examples

More about MAX()

See also: MIN()


ΓòÉΓòÉΓòÉ 119.1. Examples ΓòÉΓòÉΓòÉ

LET x1 = 84
LET x2 = 9
LET result = MAX(x1, x2, 43)   ! result is 84.

LET y1[0]'TYPE = "DATE"
LET y1 = "10-5-94"
LET y2[0]'TYPE = "DATE"
LET y2 = "2-11-94"
LET result = MAX(y1[0], y2[0])   ! result is 2-11-94

Examples source library:


ΓòÉΓòÉΓòÉ 119.2. More about MAX() ΓòÉΓòÉΓòÉ

o If any expression refers to the dictionary entry of a vector, it is treated
  as a reference to the whole vector. A complete array referenced in this way
  is treated as an additional series of individual values.

o Automatic conversions to date and time use their default formats.

o If any expression is NULL, then it is ignored.


ΓòÉΓòÉΓòÉ 120. MESSAGE ΓòÉΓòÉΓòÉ

The MESSAGE statement displays messages on the screen.

ΓöÇΓöÇMESSAGE(messageid,0,text)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Examples

More about MESSAGE

See also: DIALOG(), ERROR, STRING(), WINDOW


ΓòÉΓòÉΓòÉ 120.1. Examples ΓòÉΓòÉΓòÉ

MESSAGE "FTB0001",0,"Starting Calculations"
MESSAGE "FTB10002",0,"MSG0001: Trace point 7 reached"
MESSAGE "FTB0003",0,"You are about to overwrite data file"
MESSAGE "FTB0004",0,"Unable to create data file"

Examples source library:


ΓòÉΓòÉΓòÉ 120.2. More about MESSAGE ΓòÉΓòÉΓòÉ

o The number of parameters must match the number of inserts defined in the
  message template. All the above templates take one parameter.

o To substitute variables into a message, either use the STRING() function to
  create the message insert or use the ERROR statement instead.

o See DIALOG() for a function that displays a message and returns a code
  representing the push button that the end user pressed.


ΓòÉΓòÉΓòÉ 121. MIN() ΓòÉΓòÉΓòÉ

The MIN() function returns the minimum value of a series of values.

         <ΓöÇ,ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöÇΓöÇMIN(ΓöÇΓöÇΓöÇexpressionΓöÇΓö┤ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Examples

More about MIN()

See also: MAX()


ΓòÉΓòÉΓòÉ 121.1. Examples ΓòÉΓòÉΓòÉ

x1 = 43
x2 = 9
x3 = 84
Result = MIN(x1,x2,x3)        !  Result is 9.

!  Now try some date comparisons.
x1 = "7-7-93"
x2 = "14-6-93"
!  Must be given a Date type.
x1[0]'TYPE = "Date"
x2[0]'TYPE = "Date"
Result = MIN(x1[0],x2[0])    !  Result is 14-6-93.

Examples source library:


ΓòÉΓòÉΓòÉ 121.2. More about MIN() ΓòÉΓòÉΓòÉ

o If any expression refers to the dictionary entry of a vector, it is treated
  as a reference to the whole vector. A complete array referenced in this way
  is treated as an additional series of individual values.

o Automatic conversions to date and time use their default formats.

o If any expression is NULL, then it is ignored.


ΓòÉΓòÉΓòÉ 122. MMFILE ΓòÉΓòÉΓòÉ

The MMFILE object class provides access to multimedia files. A file that
contains sound can be played or recorded through the default sound device
provided by Multimedia Presentation Manager/2 (MMPM). A file that contains
digital video can be displayed in a default MMPM window or in an ASL window.

Attributes

Actions

Events

Examples

More about MMFILE

See also: SOUND, and the multimedia sample in the Development Samples folder.


ΓòÉΓòÉΓòÉ 122.1. Attributes ΓòÉΓòÉΓòÉ

ASYNCHRONOUS            CODE
EXCLUSIVE               LENGTH
LOCATION                NAME
ORIGIN                  POSITION
READONLY                REASON
SIZEX                   SIZEY
STATUS                  TIMEFORMAT
TIMEOUT                 TRACELEVEL
VISIBLE                 VOLUME
X                       XEXTENT
Y                       YEXTENT


ΓòÉΓòÉΓòÉ 122.1.1. ASYNCHRONOUS ΓòÉΓòÉΓòÉ

Whether the PLAY and RECORD actions are to operate asynchronously:

0         Synchronous operation
1         Asynchronous operation
If asynchronous operation is specified, control is passed to the next statement
immediately, while the playback or recording continues. If synchronous
operation is specified, control is not returned to the program until the action
has completed.

Default: 0 (Synchronous)


ΓòÉΓòÉΓòÉ 122.1.2. CODE ΓòÉΓòÉΓòÉ

Most recent error code from the MMPM command interface. Can be queried but not
modified.

Default: None


ΓòÉΓòÉΓòÉ 122.1.3. EXCLUSIVE ΓòÉΓòÉΓòÉ

Whether the application has exclusive use of the multimedia device:

0         The device is never acquired for exclusive use and is acquired for
          shared use every time read or write access is required.
1         The device is acquired for exclusive use every time read or write
          access is required and is released when the access is complete.
2         The device is acquired for exclusive use at all times.
3         The device is acquired for exclusive use every time read or write
          access is required and is released when the access is complete. Use
          of the device is denied to other users.
4         The device is acquired for exclusive use at all times. Use of the
          device is denied to other users.

For recording, use 3 or 4. For playback, use 1 or 2 if you want to ensure that
it will not be interrupted.

The values 3 and 4 differ from the values 1 and 2, respectively, only for
devices that support multiple active users (for example, a stereo sound card
that supports two mono users simultaneously). Use 3 and 4 only if you need to
exclude other users, for example, during recording.

If the value is not 2 or 4, actions, modifications, and queries may fail due to
a device being locked. An attempt to modify this attribute will fail if the
modification implicitly requires the device to be acquired and it is locked. In
these cases, the CODE and REASON attributes report that the device is locked.

Default: 0


ΓòÉΓòÉΓòÉ 122.1.4. LENGTH ΓòÉΓòÉΓòÉ

The length of the multimedia file, in the format specified by the TIMEFORMAT
attribute. If the length cannot be determined, the value is 0. Can be queried
but not modified.

Default: None


ΓòÉΓòÉΓòÉ 122.1.5. LOCATION ΓòÉΓòÉΓòÉ

Location (the OS/2 path) of the multimedia file or a STREAM object. Set on
OPEN, then read-only.

Default: None


ΓòÉΓòÉΓòÉ 122.1.6. NAME ΓòÉΓòÉΓòÉ

Name of the multimedia file. The name of a STREAM object can be used, but if
the RECORD action is used, the stream cannot be enlarged beyond the size of its
contents when the object was opened.

A combination of elements can be opened by giving a name in the form
ABC.EXT+ELTNAME, for example, "sounds.bnd+train.wav". The extension EXT is
assumed to identify an installed I/O procedure, which is called to perform I/O
on the file. If the extension is BND, the file is opened by the BND I/O
procedure supplied with the system. ELTNAME can be of the form ABC.EXT followed
by a plus sign. The file name is parsed from right to left, so the first I/O
procedure called belongs to the rightmost extension after the plus sign. The
I/O procedure must be already installed and be able to further parse the file
name, if required.

Set on OPEN, then read-only.


ΓòÉΓòÉΓòÉ 122.1.7. ORIGIN ΓòÉΓòÉΓòÉ

The corner of the enclosing window to be taken as the origin. The position of
the multimedia object is measured from this point. This attribute applies only
to video displayed in an ASL window.

"TL"      Top left
"TR"      Top right
"BL"      Bottom left
"BR"      Bottom right

Default if the parent is a window: "BL". Default otherwise: Not applicable


ΓòÉΓòÉΓòÉ 122.1.8. POSITION ΓòÉΓòÉΓòÉ

The current position of the multimedia file, in the format specified by the
TIMEFORMAT attribute. If the position cannot be determined, the value is 0. Can
be queried or modified.

Default: None


ΓòÉΓòÉΓòÉ 122.1.9. READONLY ΓòÉΓòÉΓòÉ

Whether the device is to be accessed in read-only mode:

0         The device is not accessed in read-only mode
1         The device is accessed in read-only mode
The RECORD and SAVE actions do not work in read-only mode. If you are using a
waveaudio device for playback only, use read-only mode. This prevents
accidental updating, allows files to be shared, and allows MMPM to perform
certain operations more efficiently.

Default: 0


ΓòÉΓòÉΓòÉ 122.1.10. REASON ΓòÉΓòÉΓòÉ

Text that explains the most recent error code. Can be queried but not modified.
Default: None


ΓòÉΓòÉΓòÉ 122.1.11. SIZEX ΓòÉΓòÉΓòÉ

Width of the display area for video. If the default MMPM window is used, this
is the width of the window, in dialog box units. If the parent object is a
window, this is the width of the display area on the window, in dialog box
units. If the device supports scaling, the image is scaled to fit the display
area. Otherwise, the image is clipped to the display area.

Default if the parent is a window: The value of the XEXTENT attribute. Default
otherwise: Device dependent.


ΓòÉΓòÉΓòÉ 122.1.12. SIZEY ΓòÉΓòÉΓòÉ

Height of the display area for video. If the default MMPM window is used, this
is the height of the window, in dialog box units. If the parent object is a
window, this is the height of the display area on the window, in dialog box
units. If the device supports scaling, the image is scaled to fit the display
area. Otherwise, the image is clipped to the display area.

Default if the parent is a window: The value of the YEXTENT attribute. Default
otherwise: Device dependent.


ΓòÉΓòÉΓòÉ 122.1.13. STATUS ΓòÉΓòÉΓòÉ

Status of the multimedia device:

"NOT READY"
"PAUSE"
"PLAY"
"RECORD"
"SEEK"
"STOP"
"UNKNOWN"

Can be queried but not modified.

Default: None


ΓòÉΓòÉΓòÉ 122.1.14. TIMEFORMAT ΓòÉΓòÉΓòÉ

The format used for length and position values in attributes and action
parameters. The valid values of this attribute and the corresponding formats
are as follows. In the "Format" column, the formats in quotes represent
strings, and the formats without quotes represent numeric data.

"BYTES"                       bbb Bytes (waveaudio)

"CHAPTERS"                    ccc Chapters (videodisk)

"FRAMES"                      fff Frames (video)

"HMS"                         "hh:mm:mm" Hours, minutes, seconds

"HMSF"                        "hh:mm:mm:mm" Hours, minutes, seconds, frames
                              (video)

"MILLISECONDS"                mmm Milliseconds

"MMTIME"                      uuu Multimedia time units (3000 per second)

"MSF"                         "mm:mm:mmf" Minutes, seconds, frames (compact
                              disc audio)

"SAMPLES"                     sss Samples (waveaudio)

"24 FRAME SMPTE"              "hh:mm:mm:mm" Hours, minutes, seconds, frames
                              (24-frame SMPTE sequencer)

"25 FRAME SMPTE"              "hh:mm:mm:mm" Hours, minutes, seconds, frames
                              (25-frame SMPTE sequencer)

"30 FRAME SMPTE"              "hh:mm:mm:mm" Hours, minutes, seconds, frames
                              (30-frame SMPTE sequencer)

"30 DROP-FRAME SMPTE"         "hh:mm:mm:mm" Hours, minutes, seconds, frames
                              (30-drop-frame SMPTE sequencer)

"SONG POINTER"                ppp Song pointer units (sequencer)

"TMSF"                        "tt:mm:mm:mm" Tracks, minutes, seconds, frames
                              (compact disc audio)

Within a string format, any nonnumeric character or sequence of nonnumeric
characters can be used as a separator.

The "MMTIME" and "MILLISECONDS" formats are supported by all multimedia
devices.

Default: "MMTIME"


ΓòÉΓòÉΓòÉ 122.1.15. TIMEOUT ΓòÉΓòÉΓòÉ

Time, in milliseconds, to wait for a device. If the device is not acquired
during this time, it is considered to be locked. The value -1 requests
unlimited waiting.

Default: -1 (Unlimited)


ΓòÉΓòÉΓòÉ 122.1.16. TRACELEVEL ΓòÉΓòÉΓòÉ

Whether a trace file, called FTBMM, is produced for diagnostic purposes.

0         Tracing off
Nonzero   Tracing on

Default: 0 (Off)


ΓòÉΓòÉΓòÉ 122.1.17. VISIBLE ΓòÉΓòÉΓòÉ

Whether the video is visible on the display.

0         Video is invisible
1         Video is visible

Default: 1 (Visible)


ΓòÉΓòÉΓòÉ 122.1.18. VOLUME ΓòÉΓòÉΓòÉ

For audio channels, the volume level as a percentage of the maximum volume
level. If the device does not support volume setting at such a fine level, the
result of querying this attribute might be slightly different from the value
set.

On stereo devices, this attribute sets the volume for both channels. If the
volume differs on each channel and this attribute is queried, the result is the
higher of the two levels.


ΓòÉΓòÉΓòÉ 122.1.19. X ΓòÉΓòÉΓòÉ

Horizontal position of the display area for video. If the default MMPM window
is used, this attribute specifies a position on the display, in pixels. If the
parent object is a window, this attribute specifies a position on the window,
in dialog box units.

Default if the parent is a window: 0. Default otherwise: Device dependent.


ΓòÉΓòÉΓòÉ 122.1.20. XEXTENT ΓòÉΓòÉΓòÉ

The horizontal extent of the image generated by the device, if any, in dialog
box units. For optimal reproduction of the image, use this value for the SIZEX
attribute. Can be queried but not modified. Default: None


ΓòÉΓòÉΓòÉ 122.1.21. Y ΓòÉΓòÉΓòÉ

Vertical position of the display area for video. If the default MMPM window is
used, this attribute specifies a position on the display, in pixels. If the
parent object is a window, this attribute specifies a position on the window,
in dialog box units. Default if the parent is a window: 0. Default otherwise:
Device dependent.


ΓòÉΓòÉΓòÉ 122.1.22. YEXTENT ΓòÉΓòÉΓòÉ

The vertical extent of the image generated by the device, if any, in dialog box
units. For optimal reproduction of the image, use this value for the SIZEY
attribute. Can be queried but not modified. Default: None


ΓòÉΓòÉΓòÉ 122.2. Actions ΓòÉΓòÉΓòÉ

COPYTO()             DISCARD()
PAUSE()              PLAY()
RECORD()             RESUME()
SAVE()               SETCUE()
STOP()


ΓòÉΓòÉΓòÉ 122.2.1. COPYTO() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇCOPYTO(destination)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

The COPYTO action copies the current multimedia object to the specified file.
destination is the fully qualified name of a file or a STREAM object.


ΓòÉΓòÉΓòÉ 122.2.2. DISCARD() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇDISCARD()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

The DISCARD action deletes the file and signals a QUIT event to the owning
task.


ΓòÉΓòÉΓòÉ 122.2.3. PAUSE() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇPAUSE()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

The PAUSE action suspends playback or recording.


ΓòÉΓòÉΓòÉ 122.2.4. PLAY() ΓòÉΓòÉΓòÉ

          ΓöîΓöÇ0ΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöÇΓöÇPLAY(ΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇ,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
          ΓööΓöÇfromΓöÇΓöÿ   ΓööΓöÇtoΓöÇΓöÿ

The PLAY action starts playing the multimedia object. If the from parameter is
omitted, playback begins at the current position, as specified in the POSITION
attribute. If the to parameter is omitted, playback continues until the end of
the data is reached. If asynchronous operation is specified in the ASYNCHRONOUS
attribute, then a QUIT event is queued to the owning task when playback ends.


ΓòÉΓòÉΓòÉ 122.2.5. RECORD() ΓòÉΓòÉΓòÉ

            ΓöîΓöÇ0ΓöÇΓöÇΓöÇΓöÇΓöÉ            ΓöîΓöÇ"INSERT"ΓöÇΓöÉ
ΓöÇΓöÇRECORD(ΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇ,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ,ΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
            ΓööΓöÇfromΓöÇΓöÿ   ΓööΓöÇtoΓöÇΓöÿ   ΓööΓöÇmodeΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

The RECORD action starts recording input data. If the from parameter is
omitted, recording begins at the current position, as specified in the POSITION
attribute. If the to parameter is omitted, recording continues until a PAUSE or
STOP action is called or, for a fixed-extent medium, until the medium is full.

The valid values for the mode parameter are:

INSERT    The new data is inserted at the position where recording is to start.

OVERWRITE The new data overwrites existing data at the position where recording
          is to start.

If the mode parameter is omitted and the device supports insertion, INSERT mode
is used. If this parameter is omitted and the device does not support
insertion, OVERWRITE mode is used. If asynchronous operation is specified in
the ASYNCHRONOUS attribute, a QUIT event will be queued to the owning task when
recording ends.


ΓòÉΓòÉΓòÉ 122.2.6. RESUME() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇRESUME()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

The RESUME action restarts a playback or recording that has been paused. The To
parameter that was specified on the call to PLAY or RECORD remains in effect.
If you want to change this parameter after a pause, call PLAY or RECORD again
instead of RESUME.


ΓòÉΓòÉΓòÉ 122.2.7. SAVE() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSAVE(ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
          ΓööΓöÇfilenameΓöÇΓöÿ

The SAVE action saves the multimedia file. If the filename parameter is
omitted, the data is written to the most recently used file.


ΓòÉΓòÉΓòÉ 122.2.8. SETCUE() ΓòÉΓòÉΓòÉ

                     ΓöîΓöÇ"SET"ΓöÇΓöÉ
ΓöÇΓöÇSETCUE(position,ΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                     ΓööΓöÇtypeΓöÇΓöÇΓöÿ

The SETCUE action sets up or removes an absolute cue point or a repeater cue
point.

An absolute cue point identifies an absolute position on the multimedia object.
Whenever the device passes that position during playback or recording, a TIMER
event is queued to the owning task. There is no limit on the number of absolute
cue points.

A repeater cue point is used to signal an event at regular intervals. The
interval is specified as a length in the format specified by the TIMEFORMAT
attribute. Every time that interval is passed during playback or recording, a
TIMER event is queued to the owning task. For example, if the interval is set
to 100 and the TIMEFORMAT is "BYTES", a TIMER event occurs every 100 bytes.
Counting starts from the beginning of the multimedia file. Only one repeater
cue point can be active at a time.

The position parameter specifies the position of an absolute cue point or the
interval for a repeater cue point. The valid values for the pype parameter are:

"SET"     Sets up an absolute cue point at the position specified by the
          Position parameter.

"REMOVE"  Removes an absolute cue point from the position specified by the
          Position parameter.

"REPEAT"  Sets up a repeater cue point based on the interval specified in the
          Position parameter or, if Position is 0, removes the repeater cue
          point.

If the type parameter is omitted, it defaults to SET.


ΓòÉΓòÉΓòÉ 122.2.9. STOP() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSTOP()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

The STOP action stops playback or recording.

Note:   If your application will subsequently restart playback or recording
        from the current position, use PAUSE instead of STOP.


ΓòÉΓòÉΓòÉ 122.3. Events ΓòÉΓòÉΓòÉ

QUIT              TIMER


ΓòÉΓòÉΓòÉ 122.3.1. QUIT ΓòÉΓòÉΓòÉ

Signaled when an asynchronous PLAY or RECORD stops, and when the DISCARD action
is called.


ΓòÉΓòÉΓòÉ 122.3.2. TIMER ΓòÉΓòÉΓòÉ

Signaled when a cue point is passed. (See the description of the SETCUE
action.)


ΓòÉΓòÉΓòÉ 122.4. Examples ΓòÉΓòÉΓòÉ

! This example plays a video in a default window. By default, the video
! plays synchronously. Therefore, the SHUT statement is not run until
! the video has stopped, even though it immediately follows the CALL.
OPEN MMFILE MyMovie,
 NAME="MACAW.AVI",
 LOCATION="C:\MMOS2\Movies"

CALL MyMovie'PLAY()
SHUT MyMovie

! This example plays a video in an ASL window.
OPEN WINDOW MyWin,
 VISIBLE=0           ! Hide it until we know how big it needs to  be

OPEN MMFILE MyMovie2, MyWin,
 NAME="MACAW.AVI",
 LOCATION="C:\MMOS2\Movies",
 X=10,
 Y=10

MODIFY MyWin,        ! Change window size based on the video size
 SIZEX=MyMovie2'SIZEX+20,
 SIZEY=MyMovie2'SIZEY+20,
 VISIBLE=1           ! Make it visible

CALL MyMovie2'PLAY()
SHUT MyMovie2

! This example plays an audio file asynchronously. A QUIT event occurs
! when playing stops.
OPEN MMFILE MyNoise,
 NAME="Applause.WAV",
 LOCATION="C:\MMOS2\Sounds",
 ASYNCHRONOUS=1,
 EXCLUSIVE=1         ! Ensure no other sound is played at same time

CALL MyNoise'PLAY()  ! Start playing the sound and continue
MESSAGE "EFD4001", "This message should be accompanied by noise"
! If the sound has not finished playing, allow it to continue
...
ON QUIT
DO
  SHUT MyNoise       ! Release the file when playing has stopped
END

Examples source library:


ΓòÉΓòÉΓòÉ 122.5. More about MMFILE ΓòÉΓòÉΓòÉ

o The MMFILE object requires MMPM to be installed on the application user's
  machine. However, MMPM is not required for compilation. MMPM is an optional
  component of OS/2 Version 2.1.

o The behavior of an instance of the MMFILE object class depends on how it is
  opened. If it is opened with an ASL window as its parent, an area of the
  window is reserved for video output. This area is defined by the X, Y,
  ORIGIN, SIZEX, and SIZEY attributes. If the parent is not a window or the
  object has no parent, any video output is displayed in a window managed by
  MMPM. In this case, the X, Y, SIZEX, and SIZEY attributes define the position
  and size of the window.

o If the multimedia file does not contain video, the attributes X, Y, SIZEX,
  SIZEY, XEXTENT, YEXTENT, ORIGIN, and VISIBLE are not applicable.

o The MMFILE object uses the default multimedia device for the type of file
  specified in the NAME and LOCATION attributes. The default devices and their
  characteristics can be changed in the settings notebook in the MMPM
  Multimedia folder.


ΓòÉΓòÉΓòÉ 123. MODIFY ΓòÉΓòÉΓòÉ

The MODIFY statement allows several attributes of an object to be changed at
the same time.

                    <ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöÇΓöÇMODIFYΓöÇΓöÇobjectΓöÇΓöÇΓöÇΓöÇ,ΓöÇΓöÇΓö¼ΓöÇatt=valueΓöÇΓö¼ΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                         ΓööΓöÇprocedureΓöÇΓöÿ

Examples

More about MODIFY

See also: LET, OPEN, PROCEDURE


ΓòÉΓòÉΓòÉ 123.1. Examples ΓòÉΓòÉΓòÉ

OPEN WINDOW MyWindow,
  VISIBLE = 0,
  SIZEX   = 70,
  SIZEY   = 30

...
! Set up variables before surfacing the window
...

MODIFY MyWindow,
  TITLE   = 'New title',
  SIZEX   = 100,
  SIZEY   = 100,
  VISIBLE = 1

Examples source library:


ΓòÉΓòÉΓòÉ 123.2. More about MODIFY ΓòÉΓòÉΓòÉ

o The MODIFY statement is used when two attributes are related so that a change
  to either one affects the other. Any changes to be made to one attribute as a
  result of modifying another attribute are delayed until after the MODIFY
  statement.

o If a procedure is used, it can contain LET statements which set attributes of
  object.  These changes are considered to be part of the MODIFY statement.

o Clones of cloned objects can be modified by placing the clone number after
  the name of the cloned object, thus:


    OPEN PUSH PushButton, MyWindow,
      X = 10,
      Y = 10,
      SIZEX = 60,
      SIZEY = 12,
      CLONES = 2,
      CLONEDIR = 4,
      CLONEGAP = 4,
      TEXT ="Push me"

    MODIFY PushButton[2],
      TEXT ="Don't push me",
      ENABLED =0

  The MODIFY statement then affects only the cloned element, not the entire
  set.  (The entire set can be modified by using [0].) Some attributes cannot
  be modified unless the clone number is included.

o It is better to carry out many changes to an object using a single MODIFY
  statement than to call a succession of separate MODIFY or LET statements.


ΓòÉΓòÉΓòÉ 124. NAME() ΓòÉΓòÉΓòÉ

The NAME() function returns the file name from a fully qualified OS/2 name.

ΓöÇΓöÇNAMEΓöÇΓöÇfullnameΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Examples

More about NAME()

See also: FULLPATH(), LOCATION()


ΓòÉΓòÉΓòÉ 124.1. Examples ΓòÉΓòÉΓòÉ

/* If String was 'D:\Data\TempFile.DAT' */
FileName = NAME(String)
/* FileName will now be 'TempFile.DAT' */

Examples source library:


ΓòÉΓòÉΓòÉ 124.2. More about NAME() ΓòÉΓòÉΓòÉ

o You can use NAME() with a DBCS fully qualified name.


ΓòÉΓòÉΓòÉ 125. NAMES ΓòÉΓòÉΓòÉ

The NAMES statement is used to produce a list of data names.

ΓöÇΓöÇNAMESΓöÇΓöÇtarget=ΓöÇΓöÇΓö¼ΓöÇempty_stringΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                    Γö£ΓöÇobjectstore_prefixΓöÇΓöñ
                    ΓööΓöÇobjectstore_groupΓöÇΓöÇΓöÿ

Examples


ΓòÉΓòÉΓòÉ 125.1. Examples ΓòÉΓòÉΓòÉ

! List all open objectstores into 'Stores'
NAMES stores = ""

! List all groups in 'MyStore', eg WINDOWS, MODULES, etc
NAMES my_groups = "mystore"

! List all items in a group, eg Names of windows in the objectstore
NAMES my_items = "mystore.windows"

! Controls on an open window called MyWin
NAMES controls = "T.MyWin"

Examples source library:


ΓòÉΓòÉΓòÉ 126. NOTHING ΓòÉΓòÉΓòÉ

The NOTHING statement indicates that no action is to be taken.

ΓöÇΓöÇNOTHINGΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Examples

More about NOTHING

See also: CASE...WHEN...OTHERWISE...END, IF ... THEN ... ELSE


ΓòÉΓòÉΓòÉ 126.1. Examples ΓòÉΓòÉΓòÉ

IF Status = "Open" & Count > 0
  THEN NOTHING
  ELSE CALL UPDATE()

CASE test
  WHEN 0
    CALL ZERO
  WHEN 1
    NOTHING
  OTHERWISE
    CALL OTHER
END

Examples source library:


ΓòÉΓòÉΓòÉ 126.2. More about NOTHING ΓòÉΓòÉΓòÉ

o The NOTHING statement can be included to help program readability.

o Some statements, such as THEN and WHEN, require a statement list. A NOTHING
  statement can be used if no action is required.

o A NOTHING statement can be used anywhere in a program.


ΓòÉΓòÉΓòÉ 127. NOVALUE() ΓòÉΓòÉΓòÉ

The NOVALUE() function checks whether a value contains no data. It returns 1
(true) if the value is NULL, or is an empty string ( ""), or is a string
containing only spaces.

ΓöÇΓöÇNOVALUE(value)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Examples

More about NOVALUE()

See also: NULL()


ΓòÉΓòÉΓòÉ 127.1. Examples ΓòÉΓòÉΓòÉ

x = NOVALUE(Null)       ! result is 1
x = NOVALUE("anything") ! result is 0
x = NOVALUE("")         ! result is 1
x = NOVALUE("    ")       ! result is 1
x = NOVALUE(47)         ! result is 0
x = NOVALUE(0)          ! result is 0

IF \NoValue(rc)   ! rc is NOT zero or Null
DO
  ...
END

Examples source library:


ΓòÉΓòÉΓòÉ 127.2. More about NOVALUE() ΓòÉΓòÉΓòÉ

o NOVALUE(x) is equivalent to  (x="" | NULL(x))


ΓòÉΓòÉΓòÉ 128. NULL ΓòÉΓòÉΓòÉ

The NULL statement identifies a particular value of a CASE expression. When the
expression takes on a value of NULL, the statement following NULL is executed.

ΓöÇΓöÇNULLΓöÇΓöÇstatementlistΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Examples

More about NULL

See also: CASE...WHEN...OTHERWISE...END, FALSE, IF ... THEN ... ELSE, TRUE


ΓòÉΓòÉΓòÉ 128.1. Examples ΓòÉΓòÉΓòÉ

DECLARE NULL CLEAR NUMERIC X
CASE (X < 10)
  TRUE
    MESSAGE "FTB0001",0,"2 - True ..."
  FALSE
    MESSAGE "FTB0001",0,"2 - False ..."
  NULL
    MESSAGE "FTB0001",0,"2 - Null ..."
END

Examples source library:


ΓòÉΓòÉΓòÉ 128.2. More about NULL ΓòÉΓòÉΓòÉ

o CASE...TRUE...FALSE...NULL...END performs a three-way test which takes
  account of NULL values. The IF statement performs a two-way test which is
  equivalent to CASE...TRUE...OTHERWISE...END.

o If a CASE expression is not present, any TRUE, FALSE, or NULL blocks are
  ignored.


ΓòÉΓòÉΓòÉ 129. NULL() ΓòÉΓòÉΓòÉ

The NULL() function tests whether a single value is NULL. If so, it returns 1
(true).

ΓöÇΓöÇNULL(expression)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Examples

More about NULL()

See also: DEFINED(), NOVALUE()


ΓòÉΓòÉΓòÉ 129.1. Examples ΓòÉΓòÉΓòÉ

DECLARE TASK NULL CLEAR CHARACTER[0] null
x = NULL(null)      ! Result is 1

CLEAR val
x = NULL(val)       ! Result is 1

val = ""
x = NULL(val)       ! Result is 0, "" is not equal to NULL

val = 0
x = NULL(val)       ! Result is 0, 0 is not equal to NULL

Examples source library:


ΓòÉΓòÉΓòÉ 129.2. More about NULL() ΓòÉΓòÉΓòÉ

o Note that a normal comparison (which tests for equal to NULL) always returns
  NULL.


ΓòÉΓòÉΓòÉ 130. OBJECT ΓòÉΓòÉΓòÉ

The OBJECT object class allows the user to group graphic primitives so as to
use them as a single object.

Parent: DEFINE

Attributes

Actions: None.

Events: None.

More about OBJECT


ΓòÉΓòÉΓòÉ 130.1. Attributes ΓòÉΓòÉΓòÉ

DEFINE                 MOVEX
MOVEY                  ORIGINX
ORIGINY                ROTATE
ROTATEX                ROTATEY
SCALEX                 SCALEY

The following standard graphics attributes are also available. They are
described in Standard graphics attributes:

COLOR                  LINESTYLE
MIX                    SELECTED
FILLCOLOR              LINEWIDTH
SELECTABLE             VISIBLE
FILLPATTERN


ΓòÉΓòÉΓòÉ 130.1.1. DEFINE ΓòÉΓòÉΓòÉ

Name of a DEFINE that this object is to be an instance of.

Default: None


ΓòÉΓòÉΓòÉ 130.1.2. MOVEX ΓòÉΓòÉΓòÉ

X coordinate of the position to which the DEFINE object has moved after
dragging.

Default: 0


ΓòÉΓòÉΓòÉ 130.1.3. MOVEY ΓòÉΓòÉΓòÉ

Y coordinate of the position to which the DEFINE object has moved after
dragging.

Default: 0


ΓòÉΓòÉΓòÉ 130.1.4. ORIGINX ΓòÉΓòÉΓòÉ

X origin from which scaling is calculated.

Default: 0


ΓòÉΓòÉΓòÉ 130.1.5. ORIGINY ΓòÉΓòÉΓòÉ

Y origin from which scaling is calculated.

Default: 0


ΓòÉΓòÉΓòÉ 130.1.6. ROTATE ΓòÉΓòÉΓòÉ

Angle to which the DEFINE object is to be rotated around the point defined by
attributes ROTATEX and ROTATEY.

Default: 0


ΓòÉΓòÉΓòÉ 130.1.7. ROTATEX ΓòÉΓòÉΓòÉ

X coordinate of the position around which the ROTATE is to be carried out.

Default: 0


ΓòÉΓòÉΓòÉ 130.1.8. ROTATEY ΓòÉΓòÉΓòÉ

Y coordinate of the position around which the ROTATE is to be carried out.

Default: 0


ΓòÉΓòÉΓòÉ 130.1.9. SCALEX ΓòÉΓòÉΓòÉ

Sets the X scale of the current object in world coordinate units.

Default: 0


ΓòÉΓòÉΓòÉ 130.1.10. SCALEY ΓòÉΓòÉΓòÉ

Sets the Y scale of the current object in world coordinate units.

Default: 0


ΓòÉΓòÉΓòÉ 130.2. More about OBJECT ΓòÉΓòÉΓòÉ

o The OBJECT primitive works on a step principle. First create a DEFINE and
  place some objects on it. Then create an OBJECT and set the DEFINE attribute
  to a previous DEFINE you wish to group with the current DEFINE. Continue like
  this until the object has been grouped.


ΓòÉΓòÉΓòÉ 131. OBJECTSTORE ΓòÉΓòÉΓòÉ

The OBJECTSTORE object class provides access to user programs, menus and
windows.

Attributes

Actions

Events: None.

More about OBJECTSTORE

See also: LIBRARY ASL, LIBRARY DLL, LIBRARY REXX, LIBRARY ENTRY


ΓòÉΓòÉΓòÉ 131.1. Attributes ΓòÉΓòÉΓòÉ

CODE                LOCATION
MODE                NAME
PREFIX              COMMENT


ΓòÉΓòÉΓòÉ 131.1.1. CODE ΓòÉΓòÉΓòÉ

Most recent OS/2 or internal error code. Read-only.


ΓòÉΓòÉΓòÉ 131.1.2. LOCATION ΓòÉΓòÉΓòÉ

Location of the file (the OS/2 path name).

Can be specified on OPEN, then read-only.

Default: "." (The current directory)


ΓòÉΓòÉΓòÉ 131.1.3. MODE ΓòÉΓòÉΓòÉ

Access mode:

"READ"    Opened with read-only access.

"WRITE"   Opened with read and write access.

"ASAP"    Opened with ASAP access (data is written back to disk as soon as
          possible).

Can be specified on OPEN, then read-only.

Default: "READ"


ΓòÉΓòÉΓòÉ 131.1.4. NAME ΓòÉΓòÉΓòÉ

OS/2 name of the file (that is, file name and extension).

Must be specified on OPEN, then read-only.


ΓòÉΓòÉΓòÉ 131.1.5. PREFIX ΓòÉΓòÉΓòÉ

The prefix (or first part of the name) which can be used to refer to data in
the objectstore.

Can be specified on OPEN, then read-only.

Default: Name of the instance


ΓòÉΓòÉΓòÉ 131.1.6. COMMENT ΓòÉΓòÉΓòÉ

A comment stored with the objectstore.

Default: None


ΓòÉΓòÉΓòÉ 131.2. Actions ΓòÉΓòÉΓòÉ

COPYEATTRS()            SAVETO()


ΓòÉΓòÉΓòÉ 131.2.1. COPYEATTRS() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇCOPYEATTRS(object)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Copies the extended attributes from another object.


ΓòÉΓòÉΓòÉ 131.2.2. SAVETO() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSAVETO(filename)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Saves the OBJECTSTORE data as a new OS/2 file.


ΓòÉΓòÉΓòÉ 131.3. More about OBJECTSTORE ΓòÉΓòÉΓòÉ

o ASL libraries are stored in objectstores.

o The objectstores used by an application are opened automatically by
  Visualizer.


ΓòÉΓòÉΓòÉ 132. ON ΓòÉΓòÉΓòÉ

The ON statement precedes and identifies the group of statements to be executed
when a given event occurs.

ΓöÇΓöÇONΓöÇΓöÇeventΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
               Γöé    <ΓöÇ,ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ    Γöé
               ΓööΓöÇ(ΓöÇΓöÇΓöÇΓöÇparameterΓöÇΓö┤ΓöÇΓöÇ)ΓöÇΓöÿ

Some events are part of the language. Others are signaled by objects.

Events that are part of the language are:

BREAK     ERROR
QUEUE     QUIT
START     STOP

Events that are signaled by user action on objects or by external events
include:

AB        ADVISE
DATA      DESKTOP
DRAG      ENTER
ESCAPE    HELP
OPEN      ORDER
PRINT     SELECT
SCROLL    SOURCE
TARGET    TIMER

Events

Examples

More about ON

See also: BREAK, ERROR, FORGIVE, QUEUE PROGRAM, RUN PROGRAM, START, STOP


ΓòÉΓòÉΓòÉ 132.1. Events ΓòÉΓòÉΓòÉ

BREAK     The ON BREAK block is activated when the end user presses Ctrl+Break,
          and the program that is running has previously been prepared to
          accept this event.

ERROR     The ON ERROR block is activated when certain execution errors occur.
          The values of the system variables A.System.ErrorLine and
          A.System.ErrorModule indicate the location of the error.
          A.System.ErrorNumber and A.System.ErrorInfo are vectors that describe
          the error.

QUEUE     The ON QUEUE block is activated by default when the program is run or
          queued from another program.  This block allows programs to
          communicate with each other without direct end-user intervention.

QUIT      The ON QUIT block is activated when Close is selected on the system
          icon.  In the case of a selection, details of the box (and panel)
          selected are noted in system variables for subsequent testing.  If
          the selection is made on the active window (holding the cursor), then
          A.System.Box is set to the box containing the cursor. If the
          selection is made on any other than the active window, A.System.Box
          is set to null.

START     The statements in the ON START block are the first to be processed
          when a program is initiated.  The ON START block is activated by a
          START request from another program.

STOP      The ON STOP block is activated when the system requires that an
          application should stop.

ADVISE    Signaled by a DDESERVER when a DDE client asks to be kept informed of
          data changes.

AB        Signaled when the menu bar is selected. The ON SELECT block is
          activated directly after the end of the AB block.

DATA      Signaled when data has changed within a data entry field, a single
          line entry field, or an entry field (also signaled by DDECLIENT if a
          connected DDE server indicates a data change).

DESKTOP   Signaled when a window is resized, maximized, minimized, or
          normalized.

DRAG      An object that is dragable can be dragged and dropped within a
          graphic area. The DRAG event, if specified, is activated when the
          object is dropped.

          The ON DRAG block is not generated automatically. Program editor's
          windows are free form however, and you can add the ON DRAG block by
          editing an existing event block and placing the code below after the
          existing block. (When the data in the window is closed, then the data
          is refreshed and new ON DRAG block is added to the event list.)

          Set a BITMAP, GRAPHIC AREA, or DEFINE to dragable by opening it with
          the DRAGABLE attribute set to 1 (yes).

ENTER     Signaled when the ENTER or RETURN key is pressed from within a data
          entry field, a single line entry field, or an entry field.

ESCAPE    Signaled when the ESCAPE key is pressed.

HELP      The ON HELP block is activated when Help is selected from the menu
          bar or by pressing F1.

INITIATE(pDDEserver)
          The ON INITIATE block is activated whenever a DDE client initiates a
          new conversation with the DDESERVER object. (If the information is
          not of interest to the program, the event need not be coded.)
          pDDEserver points to the DDESERVER that raised the event.

OPEN      Mouse button 1 is clicked twice on a graphic object or list box.

ORDER     The ORDER window is selected in VIEWORDER.

PRINT     The PRINT event is activated when a request for opening a printer has
          been made in the program.  A dialog window may have been presented to
          the user for selection from a list of printers. PRINT passes a single
          parameter, which is the handle of an open PRINTER object.

SCROLL    Signaled when a scroll bar is activated. However, some objects such
          as ENTRY and LIST handle their own scrolling. Refer to the individual
          objects for details.

SELECT    Signaled when object or window is selected using the mouse or
          keyboard.

SOURCE    Signaled by a request for data by DDESERVER, DDECLIENT, CLIPBOARD,
          SOURCECTRL, or COPYTO.

TARGET    Signaled by a delivery of data by DDESERVER, DDECLIENT, CLIPBOARD,
          TARGETCTRL, or LINK.

TIMER     A timer has reached its set point and the event has reached the top
          of the event queue.


ΓòÉΓòÉΓòÉ 132.2. Examples ΓòÉΓòÉΓòÉ


ON PRINT(pPrinter)
DO
  DECLARE POINTER pPrinter
  ! Write output to the printer object
  ...
  SHUT ?pPrinter
END

ON QUEUE(Type,pObject)
DO
  DECLARE CHAR[30] Type
  DECLARE POINTER  pObject
  ...
END

This block will be executed should there be a run time error.

ON ERROR
DO
  !
  ! Message to identify failing module and line
  LET ans=DIALOG("FTB7004",0,
   A.System.ErrorModule ,
   A.System.ErrorLine )
  DO i=1 : A.System.ErrorNumber[0]'ENTRIES
    IF ans = "CANCEL"
      TERMINATE
      ! Display system message corresponding to error
    LET ans = DIALOG ('FTB'||
     A.System.Errornumber[i], 0,
     A.System.ErrorInfo[i])
  END
  STOP
END

This block is executed when the user uses Close in the system menu.

ON QUIT
DO
  /*-----------------------------------*/
  /* Which object requested to be shut */
  /*-----------------------------------*/
  CASE WORDS(A.System.Object,-1,".")

    WHEN "MyChart"    ! Special case for an IBMCHART shutting
      ! Do nothing. Leave the chart active, but invisible
      ! so it can be refreshed with new data and re-opened later.
...
      CALL MyChart'OPEN()

    WHEN "MyWindow"
    DO
      ! Add any processing that's needed before stopping
...
      SHUT MyChart
      SHUT MyTable
      STOP
    END

    OTHERWISE   ! General case is to simply shut the obejct.
      SHUT ?A.System.Object
  END
END

This block is executed to initialize the program. Each program will have its
own libraries to open and variables to initialize, the example below is
typical.

ON START
DO
  !
  ! Open the user library
  OPEN OBJECTSTORE MyLib,
   NAME     = "UserLib.A95" ,
   LOCATION = S.Control.Path

  LIBRARY ASL "MyLib..AppDevl",
   ImportData,
   ExportData

  OPEN WINDOW MyWindow,
   TITLE = 'Test window called MyWindow',
   SIZEX = 160,
   SIZEY = 20
  ...
END


  ! Now create an instance of a Chart object

  OPEN IBMCHART MyChart,
   NAME       = "My Chart",       ! Title of the chart
   IDENTIFIER = "J:\dss\chart"    ! Filename of chart
...
! Other Chart attributes can be added to the OPEN
! and actions to define what data to show can be added
! before it's displayed on the screen.
...
   CALL MyChart'OPEN()       ! Finally show the Chart


  ! Now create an instance of a Table object

  OPEN IBMTABLE MyTable,
   NAME       = "My Data",        ! Title of the table
   IDENTIFIER = "I:\dss\table"    ! Filename of table
...
! Other Table attributes can be added to the OPEN
! and actions to define what data to show can be added
! before it's displayed on the screen.
...
   CALL MyTable'OPEN()       ! Finally show the table

!END

The STOP event is used to terminate the program.  Note that there is both a
STOP event and a STOP statement.

ON STOP
DO
  STOP
END

Example of ON DRAG

If you are coding an application that allows graphic objects to be dropped upon
each other, you will need to detect which two objects were involved in a single
event.

The following example shows one way of identifying the objects.

   ON DRAG
    ! Assuming the graphics area is called MainG1
    ! and was opened as dragable
    ! Find out which objects were involved in the drag
    LET StartX =  A.System.PositionX
    LET StartY =  A.System.PositionY
    DEFINE Objects
    CALL MainG1'SELECT(
       Objects,         ! return the objects found
                        ! within the tolerance
       2,               ! just the first 2 found (top first)
       StartX,          ! at position X,Y
       StartY,          !
       10,              ! X tolerance
       10)              ! Y tolerance
       ! Array Objects should then be a 2 element array
       ! containing the identifiers of the objects found
     IF Entries("Objects")>0
      DO
        DraggedObj=Objects[1]
        DroppedonObj=Objects[2]
        ParentObj=(?DraggedObj)'PARENT
        ! This statement will put the DEFINEd object
        ! back in the original X,Y position. A different
        ! application might want to reposition the dragged object
        ! to the new site. To do this you would alter X, Y for the
        ! dragged object before doing this modify.
        MODIFY (?ParentObj),
         MOVEX=0,
         MOVEY=0
      END
END

Examples source library:


ΓòÉΓòÉΓòÉ 132.3. More about ON ΓòÉΓòÉΓòÉ

o ON can be followed by a single statement or multiple statements. Multiple
  statements must be grouped in a DO ... END block.

o An ON block cannot be nested within another block.

o A program need not contain blocks for ON conditions it does not handle. Thus,
  a program that does not open any windows with menu bars need not contain an
  ON AB block.

o When an error is encountered, then control is passed to the ON ERROR block.
  The event block in which the error occurred is abandoned. An execution error
  in an ON ERROR block terminates the program.

o When a Ctrl+Break signal is received, its effect is governed by the BREAK
  statement.  If the program is prepared to accept Ctrl+Break, control is
  passed to the ON BREAK block and the event block that was interrupted is
  abandoned.


ΓòÉΓòÉΓòÉ 133. OPEN ΓòÉΓòÉΓòÉ

The OPEN statement creates an object from an object class.

ΓöÇΓöÇOPENΓöÇΓöÇclassΓöÇΓöÇinstanceΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                                       <ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼Γö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
   Γö£ΓöÇ,ΓöÇΓöÇΓöÇΓöÇparentΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ   Γö£ΓöÇ,attr=valueΓöÇΓöÇΓöñ
   ΓööΓöÇ,ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇ,ΓöÇΓöÇsaved_objectΓöÇΓöÿ   ΓööΓöÇ,proc(parms)ΓöÇΓöÿ
        ΓööΓöÇparentΓöÇΓöÿ

Examples

More about OPEN

See also: DECLARE, LET, MODIFY, SHUT


ΓòÉΓòÉΓòÉ 133.1. Examples ΓòÉΓòÉΓòÉ

OPEN WINDOW main_entry,,"I.windows.basic_window",
     title="The main window",bgcolor="blue"

In the above example, an instance of the WINDOW object class is opened called
main_entry. It does not have a parent window.  It is a window which was
compiled using the window editor. Its attribute values are defined by the
values saved in the user.basic_window object, but two of those saved
attributes, title and bgcolor, are overwritten by the new values supplied with
the statement.

LET Class  = 'IBMCHART'
LET Handle = POINTER('Object1')

OPEN ?Class ?Handle ,         ! Optional Parent not used for Charts.
 IDENTIFIER = "J:\dss\Chart", ! As part of the Open statement the
 SetName( Class , Handle )    ! SetName() function will use logic to
                              ! decide how to set the Name attribute

CALL (?Handle)'OPEN()         ! Finally, display the object

LET Class  = 'IBMTABLE'
LET Handle = POINTER('Object2')

OPEN ?Class ?Handle ,         ! This time the SetName function will
 IDENTIFIER = "I:\dss\Table", ! set the Name attribute differently.
 SetName( Class , Handle )

CALL (?Handle)'OPEN()


PROCEDURE SetName(Class,Object)
DO
  DECLARE CHAR[*] Class
  DECLARE POINTER Object

  CASE Class
    WHEN 'IBMCHART'
    DO
      LET (?Handle)'NAME = "Special attribute manipulations for Chart"
    END
    OTHERWISE
      LET (?Handle)'NAME = "Normal attribute manipulation"
  END
END

Examples source library:


ΓòÉΓòÉΓòÉ 133.2. More about OPEN ΓòÉΓòÉΓòÉ

o Objects are shut using the SHUT statement.

o All objects opened by a task are shut by the system when the task stops.

o If a procedure is used, it can use the LET statement to assign values to
  attributes.

o You can change an object attribute by assigning to it, just like a variable.
  Refer to an attribute of an object by using the object name followed by the
  attribute name, separated by an apostrophe. For example:

    Main_Entry'BGCOLOR = 'Red'

  Many attributes can only be modified if a clone level is specified, however.
  To modify a single clone level, insert [clonenumber] before the apostrophe.
  To modify all clones, use a clonenumber of 0.

o To change more than one attribute at a time, use the MODIFY statement.

o Note that some attributes cannot be changed after the object is opened. The
  MODE attribute of the FILE object, for example. If MODE is set to "READ" when
  the FILE object is opened, it cannot later be changed to "WRITE".

  Such attributes must be set when the OPEN statement is used.

o Once the object is opened, it can generate events and calls can be made to
  any actions associated with it.

  The example below uses the system object to delete a file. Note that the
  FORGIVE statement is issued before to the call to the DELETE action in case
  the table does not exist.

      ! erase the old table
      OPEN SYSTEM Sys
      FORGIVE CALL Sys'DELETE("D:\Address")
      SHUT Sys


ΓòÉΓòÉΓòÉ 134. OTHERWISE ΓòÉΓòÉΓòÉ

The OTHERWISE statement is an optional last clause of a CASE construct. It
introduces statements to be executed if the value of the CASE expression has
not been identified by the related WHEN clauses.

ΓöÇΓöÇOTHERWISEΓöÇΓöÇstatementlistΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Examples

See also: CASE...WHEN...OTHERWISE...END, ELSE, WHEN


ΓòÉΓòÉΓòÉ 134.1. Examples ΓòÉΓòÉΓòÉ

CASE Char
  WHEN "a"
    CharVal = "First Letter"
  WHEN "z"
    CharVal = "Last Letter"
  OTHERWISE
    CharVal = "Other Letter"
END

CASE test
  NULL
    CALL NEW
  OTHERWISE
    CALL REPLACE
END

Examples source library:


ΓòÉΓòÉΓòÉ 135. OUTLINE ΓòÉΓòÉΓòÉ

The OUTLINE graphics primitive object class creates an instance of an open
irregular polygon.

Parent: DEFINE

Attributes

Actions: None.

Events: None.

Examples


ΓòÉΓòÉΓòÉ 135.1. Attributes ΓòÉΓòÉΓòÉ

CLOSINGLINE            ENCLOSED
REFERENCE

The following standard graphics attributes are also available. They are
described in Standard graphics attributes:

BOUNDED                FILLCOLOR
LINEWIDTH              SELECTED
COLOR                  FILLPATTERN
MIX                    VISIBLE
CONSTANT               LINESTYLE
SELECTABLE


ΓòÉΓòÉΓòÉ 135.1.1. CLOSINGLINE ΓòÉΓòÉΓòÉ

Polygon is closed with a line joining the first point to the last:

0         Polygon not closed
1         Polygon closed

Default: 0 (Not closed)


ΓòÉΓòÉΓòÉ 135.1.2. ENCLOSED ΓòÉΓòÉΓòÉ

Polygon is treated as an enclosed object which can be filled:

0         Polygon not enclosed
1         Polygon enclosed

Default: 1 (Enclosed)


ΓòÉΓòÉΓòÉ 135.1.3. REFERENCE ΓòÉΓòÉΓòÉ

Vector defining the coordinates of each angle of the polygon. This vector
consists of the following elements:

1         X coordinate of point 1
2         Y coordinate of point 1

Any number of points can be defined. All coordinates are in world coordinate
units.

Set on OPEN, then read-only.

Default: ""


ΓòÉΓòÉΓòÉ 135.2. Examples ΓòÉΓòÉΓòÉ

PROCEDURE OutLine()
DO
  ! Open an OUTLINE graphic primative
  ! This example is 2 irregular triangles overlapping.
  ! Set up a vector of the coordinates.
  DEFINE Array[0]
  INSERT Array[0] = 100   ! X coord. of point 1
  INSERT Array[0] = 100   ! Y coord. of point 1
  INSERT Array[0] = 100   ! X coord. of point 2
  INSERT Array[0] = 300   ! Y coord. of point 2
  INSERT Array[0] = 200   ! X coord. of point 3
  INSERT Array[0] = 350   ! Y coord. of point 3

  OPEN OUTLINE Out1, Def1,   ! Define Def1 must already exist
   REFERENCE = Array[0],
   FILLCOLOR = "Red",
   CONSTANT  = 1

  LET Array[6] = 50

  OPEN OUTLINE Out2, Def1,   ! 2nd OutLine on the same Define.
   REFERENCE = Array[0],
   FILLCOLOR = "Green",
   CONSTANT  = 1


END

Examples source library:


ΓòÉΓòÉΓòÉ 136. OVERLAY() ΓòÉΓòÉΓòÉ

The OVERLAY() function returns the string it is given, with part of it replaced
by another string.

                           ΓöîΓöÇ1ΓöÇΓöÇΓöÇΓöÉ             ΓöîΓöÇ" "ΓöÇΓöÉ
ΓöÇΓöÇOVERLAY(target,repstr,ΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇ,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ,ΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                           ΓööΓöÇnumΓöÇΓöÿ   ΓööΓöÇlenΓöÇΓöÿ   ΓööΓöÇpadΓöÇΓöÿ

Examples

More about OVERLAY()

See also: COVERLAY(), DELWORD()


ΓòÉΓòÉΓòÉ 136.1. Examples ΓòÉΓòÉΓòÉ

new = OVERLAY("123abc456","xyz",4)
                             !  new is "123xyz456".
new = OVERLAY("123abc456","xyz",4,4)
                             !  new is "123xyz56".
new = OVERLAY("123456","xyz",4,0)
                             !  new is "123xyz456".

Examples source library:


ΓòÉΓòÉΓòÉ 136.2. More about OVERLAY() ΓòÉΓòÉΓòÉ

o If you expect your application to be used in a DBCS environment, and you want
  to work with characters only, then use COVERLAY(). If you are working in an
  SBCS environment only, use OVERLAY().

o If repstr is positioned such that it exceeds or overlaps the length of
  target, the returned string is extended automatically. However, if the length
  of this extended string would exceed the system limit for strings, an error
  is returned.

o An error is returned if number or length is negative or NULL. Real numbers
  are truncated.

o Using a string parameter of type NULL in this function produces a result of
  NULL.

o Any pad parameter must be a one-character string. DBCS characters cannot be
  used as pad characters.

o In a DBCS environment only:

   - number refers to the number of the byte in the string (not necessarily the
     character position). If byte number is the second half of a DBCS
     character, the first byte is replaced by an SBCS space.

   - If the last byte position to be overlapped is the first byte of a DBCS
     pair, the second byte of that pair is replaced by an SBCS space.

   - If you need to work on characters rather than bytes in an DBCS
     environment, use COVERLAY() rather than OVERLAY().


ΓòÉΓòÉΓòÉ 137. PAD() ΓòÉΓòÉΓòÉ

The PAD() function returns a string padded up to a specified length with a
specified character.

                              ΓöîΓöÇ"L"ΓöÇΓöÇΓöÉ     ΓöîΓöÇ" "ΓöÇΓöÉ      ΓöîΓöÇ"B"ΓöÇΓöÇΓöÇΓöÉ
ΓöÇΓöÇPAD(stringΓöÇΓöÇ,ΓöÇΓöÇlengthΓöÇΓöÇ,ΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇ,ΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇ,ΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                              ΓööΓöÇtypeΓöÇΓöÿ     ΓööΓöÇpadΓöÇΓöÿ      ΓööΓöÇstripΓöÇΓöÿ

Examples

More about PAD()

See also: CPAD()


ΓòÉΓòÉΓòÉ 137.1. Examples ΓòÉΓòÉΓòÉ

padded_string = PAD("    asdf",8,"T","*","L")
                   !  padded_string is "asdf****"
pad_string = PAD("asdf    ",0)
                   !  pad_string is "    asdf" (no trailing spaces)
pad_string = PAD("   asdf   ",0,,"o","B")
                   !  pad_string is "ooooooasdf" (no leading or trailing spaces)
                   !  Note: Use TRIM() to remove Leading and trailing spaces.

Examples source library:


ΓòÉΓòÉΓòÉ 137.2. More about PAD() ΓòÉΓòÉΓòÉ

o An error is returned if length is negative or NULL. Real numbers are
  truncated.

o Using a string parameter of type NULL in this function produces a result of
  NULL.

o If an odd number of characters are added with padding type C, the right-hand
  end of the string gains one more character than the left.

o Only SBCS characters can be used as pad characters. DBCS characters cannot be
  used.

o If removal of spaces is specified by the strip parameter, both SBCS and DBCS
  spaces are removed.


ΓòÉΓòÉΓòÉ 138. PAGE() ΓòÉΓòÉΓòÉ

The PAGE() function returns a format value which specifies that one or more new
pages are required in the output file when this value is written to an output
device (such as a printer) which supports lines of output.

ΓöÇΓöÇPAGE(ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
          ΓööΓöÇexpressionΓöÇΓöÿ

Examples

More about PAGE()

See also: LINE(), PRINTER, SPACE()


ΓòÉΓòÉΓòÉ 138.1. Examples ΓòÉΓòÉΓòÉ

CALL Print'PUT("Page ",Pg_Num,LINE(2),"Name ",EmpName,PAGE())
LET Ff=PAGE(1)
...
LET Ff'COUNT=2                          !  Leave a blank page.
CALL print'PUT(Heading1,Ff)

In the example above, the third statement shows how the COUNT attribute of a
format variable (Ff) can be changed to set the number of pages required in the
output file.

Examples source library:


ΓòÉΓòÉΓòÉ 138.2. More about PAGE() ΓòÉΓòÉΓòÉ

o Format values of PAGE() are displayed on the screen as PAGE. The COUNT
  attribute is not displayed.

o The PAGE() function can be used with LET and IF statements.

o PAGE(n) causes  n-1 completely blank pages.


ΓòÉΓòÉΓòÉ 139. PLENGTH() ΓòÉΓòÉΓòÉ

The PLENGTH() function provides the number of dialog units taken up by a
character string. It is used for finding the size of proportional font text
strings.

ΓöÇΓöÇPLENGTH(string,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                    ΓööΓöÇwindowΓöÇΓöÿ

Examples

See also: WINDOW (FONT attribute)


ΓòÉΓòÉΓòÉ 139.1. Examples ΓòÉΓòÉΓòÉ


OPEN WINDOW WinBig, FONT = "14.Helv"
units=PLENGTH("Will this string fit in the space?",WinBig)
                 !  units = 117
                 !  The result depends on the font of the window
OPEN WINDOW WinSmall, FONT = "6.Helv"
units=PLENGTH("Will this string fit in the space?",WinSmall)
                 !  units = 136

Examples source library:


ΓòÉΓòÉΓòÉ 140. POINT ΓòÉΓòÉΓòÉ

The POINT graphics primitive object class creates an instance of a marker
symbol.

Parent: DEFINE

Attributes

Actions: None.

Events: None.

Examples


ΓòÉΓòÉΓòÉ 140.1. Attributes ΓòÉΓòÉΓòÉ

CELLX                 CELLY
REFERENCE             STYLE
WIDTH

The following standard graphics attributes are also available. They are
described in Standard graphics attributes:

COLOR                 MIX
SELECTED              VISIBLE
CONSTANT              SELECTABLE


ΓòÉΓòÉΓòÉ 140.1.1. CELLX ΓòÉΓòÉΓòÉ

Width of the point in world coordinate units.

Default: 0


ΓòÉΓòÉΓòÉ 140.1.2. CELLY ΓòÉΓòÉΓòÉ

Height of the point in world coordinate units.

Default: 0


ΓòÉΓòÉΓòÉ 140.1.3. REFERENCE ΓòÉΓòÉΓòÉ

Vector defining the position of the point. This vector consists of the
following elements:

1         X coordinate of the point
2         Y coordinate of the point

Coordinates are in world coordinate units.

Any number of points can be defined.

Set on OPEN, then read-only.

Default: ""


ΓòÉΓòÉΓòÉ 140.1.4. STYLE ΓòÉΓòÉΓòÉ

Style of point. Eleven styles are available:

0         Invisible
1         Multiplication sign
2         Plus sign
3         Open diamond
4         Open box
5         6-pointed asterisk
6         8-pointed asterisk
7         Solid diamond
8         Solid square
9         Dot
10        Open circle

Default: 0 (Invisible)


ΓòÉΓòÉΓòÉ 140.1.5. WIDTH ΓòÉΓòÉΓòÉ

Width of point in pixels.  Range is from 1 through maximum screen width. If
CELLX and CELLY are specified, the width is ignored.

Default: 3 (Standard character cell size)


ΓòÉΓòÉΓòÉ 140.2. Examples ΓòÉΓòÉΓòÉ


! Sample of use of graphic POINT object
! Opens four different samples using different styles of point.
! The Style attribute takes a value between 0 & 10
!
! Produce a 'diamond'
!
DEFINE parr[2]
LET parr[1]=200                 ! x coord of point
LET parr[2]=130                 ! y coord of point

  OPEN POINT point1,def1,
   REFERENCE = parr[0],
   CELLX = 50, CELLY = 50,
   STYLE = 3,  WIDTH = 5,
   COLOR = "Blue"

!
! Produce a '6-pointed asterisk'
!

LET parr[1] += 200

OPEN POINT Point2, Def1,
 REFERENCE = parr[0],
 CELLX = 50, CELLY = 50,
 STYLE = 5,  WIDTH = 5,
 COLOR = "Red"

!
! produce a 'filled square'
!

LET parr[1] += 200
OPEN POINT point3, Def1,
 REFERENCE = parr[0],
 CELLX = 50, CELLY = 50,
 STYLE = 8,  WIDTH = 5,
 COLOR = "Black"

!
!produce an "8-pointed asterisk"
!

LET parr[2] += 200

OPEN POINT point4, Def1,
 REFERENCE = parr[0],
 CELLX = 15, CELLY = 15,
 STYLE = 6,  WIDTH = 5,
 COLOR = 5  ! cyan

Examples source library:


ΓòÉΓòÉΓòÉ 141. POINTER() ΓòÉΓòÉΓòÉ

The POINTER() function returns a pointer value that identifies a variable or
array element.

                     ΓöîΓöÇ1ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ   ΓöîΓöÇ1ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöÇΓöÇPOINTER(varname,ΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇ,ΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                     ΓööΓöÇelement1ΓöÇΓöÿ   ΓööΓöÇelement2ΓöÇΓöÿ

Examples

More about POINTER()

See also: DECLARE

Also see Operators.


ΓòÉΓòÉΓòÉ 141.1. Examples ΓòÉΓòÉΓòÉ

LET p=POINTER(lines[0])
LET (?p)[1]=0
LET x=(?p)[i]

In the above example, the second statement assigns a zero to the first element
of the array variable lines. The third statement assigns the i'th element of
lines to x. The value is held in a variable with a name which may not be known
until execution time, but the name is itself held in the variable.

Notice that the indirection operator ( ?) is used to evaluate the expression
following it as a pointer to a variable.

Examples source library:


ΓòÉΓòÉΓòÉ 141.2. More about POINTER() ΓòÉΓòÉΓòÉ

o You can use POINTER() with the indirection operator ( ?) to refer to the
  given variable.

o You can specify the variable as a string, for example: POINTER("LINES"). Or
  you can specify it as a reference to the dictionary, for example:
  POINTER(LINES[0]). To point to a declared variable, you can only use the form
  that is a reference to a dictionary.

o When using the indirection operator ( ?) on a pointer to an object, be sure
  to allow for its lower level of precedence:


    pName=POINTER("A.."||ObjectName)
    (?pName)'TITLE = "New Value"

o Using indirection with pointers can increase performance over using
  indirection with strings.

o The element number contained in a pointer variable is used if there is no
  explicit subscript on the reference.


ΓòÉΓòÉΓòÉ 142. POLYGON ΓòÉΓòÉΓòÉ

The POLYGON graphics primitive object class creates an instance an open regular
polygon.

Parent: DEFINE

Attributes

Actions: None.

Events: None.

Examples


ΓòÉΓòÉΓòÉ 142.1. Attributes ΓòÉΓòÉΓòÉ

REFERENCE

The following standard graphics attributes are also available. They are
described in Standard graphics attributes:

BOUNDED                FILLCOLOR
LINEWIDTH              SELECTED
COLOR                  FILLPATTERN
MIX                    VISIBLE
CONSTANT               LINESTYLE
SELECTABLE


ΓòÉΓòÉΓòÉ 142.1.1. REFERENCE ΓòÉΓòÉΓòÉ

Vector defining the position of one side of the polygon and the number of
sides. This vector consists of the following elements:

1         X coordinate of the start of the side
2         Y coordinate of the start of the side
3         X coordinate of the end of the side
4         Y coordinate of the end of the side
5         Number of sides.

If the position of the start of the side is above the position of the end, the
polygon is drawn to the right of the line. If the position of the start of the
side is below the position of the end, the polygon is drawn to the left of the
line.

All coordinates are in world coordinate units.

Set on OPEN, then read-only.

Default: ""


ΓòÉΓòÉΓòÉ 142.2. Examples ΓòÉΓòÉΓòÉ

! Open an instance of a POLYGON graphic object. This example
! opens a simple 7 sided polygon.
PROCEDURE POLYGON
DO

  DEFINE Array[0]
  INSERT Array[1] = 200             ! x coord start of side
  INSERT Array[2] = 100             ! y coord start of side
  INSERT Array[3] = 250             ! x coord end of side
  INSERT Array[4] = 150             ! y coord end of side
  INSERT Array[5] = 7               ! number of sides

  OPEN POLYGON poly1, Def1,
   REFERENCE =Array[0]

END

Examples source library:


ΓòÉΓòÉΓòÉ 143. POSITION() ΓòÉΓòÉΓòÉ

The POSITION() function returns a format value which specifies that spaces are
to be added to the output so that the next character will occupy the indicated
position. The first character in a record is position 1. The command is valid
only for output devices which support lines of output (PRINTER and FILE for
example).

ΓöÇΓöÇPOSITION(expression)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Examples

See also: LINE(), PAGE(), PRINTER, SPACE(), TAB()


ΓòÉΓòÉΓòÉ 143.1. Examples ΓòÉΓòÉΓòÉ


CALL print'PUT("Pages:",POSITION(11),Totpage)

Examples source library:


ΓòÉΓòÉΓòÉ 144. PRECISION ΓòÉΓòÉΓòÉ

The PRECISION statement specifies the maximum number of decimal places for the
result of a calculation.

ΓöÇΓöÇPRECISIONΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
               Γö£ΓöÇdecimal_placesΓöÇΓöñ
               ΓööΓöÇ*ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

Examples

More about PRECISION


ΓòÉΓòÉΓòÉ 144.1. Examples ΓòÉΓòÉΓòÉ

PRECISION 3
Result = 2.29 * 3.3638                 !  Result = 7.703

Note that the numbers are rounded after a calculation is performed. For
example, if a precision of 2 decimal places is specified:

  1.114       1.115
 +1.114      +1.115
-------     -------
  2.23        2.23
-------     -------

Examples source library:


ΓòÉΓòÉΓòÉ 144.2. More about PRECISION ΓòÉΓòÉΓòÉ

o The default value for  decimal_places is set at startup (using PROFILE).

o The value set by a PRECISION statement only applies to the task in which that
  PRECISION statement is invoked. Within a task, a PRECISION statement resets
  the precision set by any previous PRECISION statement.

o There is a distinction between precision, which can be up to 40 decimal
  places, and the maximum number of significant figures in the decimal
  fraction, which is 15.

o It is advisable to set a value for PRECISION which is equal to or greater
  than that of the most precise data being used. Truncation will occur if a
  lower value is used. This can have an unpredictable effect on calculations.


ΓòÉΓòÉΓòÉ 145. PRESSPACE ΓòÉΓòÉΓòÉ

The PRESSPACE object provides an area in a window which can be subclassed using
an application specific Presentation Manager window procedure.

Parent: WINDOW

Attributes

Actions

Events

More about PRESSPACE


ΓòÉΓòÉΓòÉ 145.1. Attributes ΓòÉΓòÉΓòÉ

X                   Y
SIZEX               SIZEY
VISIBLE             ORIGIN
DLL                 PROCNAME


ΓòÉΓòÉΓòÉ 145.1.1. X ΓòÉΓòÉΓòÉ

Horizontal position of the PRESSPACE within the enclosing window, in dialog box
units.

Default: 0


ΓòÉΓòÉΓòÉ 145.1.2. Y ΓòÉΓòÉΓòÉ

Vertical position of the PRESSPACE within the enclosing window, in dialog box
units.

Default: 0


ΓòÉΓòÉΓòÉ 145.1.3. SIZEX ΓòÉΓòÉΓòÉ

Horizontal size of the PRESSPACE, in dialog box units.

Default: 0


ΓòÉΓòÉΓòÉ 145.1.4. SIZEY ΓòÉΓòÉΓòÉ

Vertical size of the PRESSPACE, in dialog box units.

Default: 0


ΓòÉΓòÉΓòÉ 145.1.5. VISIBLE ΓòÉΓòÉΓòÉ

Whether the PRESSPACE is displayed:

0         Not displayed
1         Displayed

Default: 1 (Displayed)


ΓòÉΓòÉΓòÉ 145.1.6. ORIGIN ΓòÉΓòÉΓòÉ

The corner of the enclosing window to be taken as the origin. The position of
the PRESSPACE is measured from this point.

"TL"      Top left
"TR"      Top right
"BL"      Bottom left
"BR"      Bottom right

Default: "BL" (Bottom left)


ΓòÉΓòÉΓòÉ 145.1.7. DLL ΓòÉΓòÉΓòÉ

Name of the Dynamic Link Library which contains the application window
procedure with which the control is subclassed.

Must be set on open, cannot be modified.


ΓòÉΓòÉΓòÉ 145.1.8. PROCNAME ΓòÉΓòÉΓòÉ

Name of the application window procedure with which the control is subclassed.

Must be set on open, cannot be modified.


ΓòÉΓòÉΓòÉ 145.2. Actions ΓòÉΓòÉΓòÉ

SEND()            POST()


ΓòÉΓòÉΓòÉ 145.2.1. SEND() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSEND(parameter1,parameter2)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Sends a defined Presentation Manager message to the control. The parameters are
sent as MP1 and MP2 to the user's window procedure.

Since sending a message is synchronous, this action will return the result set
in the window procedure.


ΓòÉΓòÉΓòÉ 145.2.2. POST() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇPOST(parameter1,parameter2)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Posts a defined message to the control. The parameters, which are sent as MP1
and MP2, must be integers, parameter1 a word and parameter2 long.


ΓòÉΓòÉΓòÉ 145.3. Events ΓòÉΓòÉΓòÉ

SIGNAL


ΓòÉΓòÉΓòÉ 145.3.1. SIGNAL ΓòÉΓòÉΓòÉ

Runs the ON SIGNAL block. The application subclass activates the ON SIGNAL
block and passes 3 parameters back to ASL. The first is the handle of the
PRESSPACE object which is signalling ASL. The other 2 parameters are the values
passed as MP1 and MP2 in the subclass. None of the system variables normally
associated with events from controls are set.


ΓòÉΓòÉΓòÉ 145.4. More about PRESSPACE ΓòÉΓòÉΓòÉ

o The PRESSPACE control allows direct access to Presentation Manager primitives
  under the control of an ASL application.

o The power and flexibility of Presentation Manager become available to ASL
  based applications.

Where applications require the power and flexibility of Presentation Manager,
and can afford to pay the price of programming to the low level Presentation
Manager APIs, the PRESSPACE control should be used.

Typically, a WINDOW would be opened from ASL, and a PRESSPACE object opened on
the client area. The window procedure used to subclass the PRESSPACE would be
packaged in a DLL. When the PRESSPACE is opened, the DLL is loaded, and the
procedure used to subclass the Presentation Manager control. A BB_CREATE
message is then sent to the subclass. This allows the subprocedure to carry out
initialization. From this point on, all Presentation Manager messages will go
to the application provided procedure. The messages can be processed or passed
to the PRESSPACE default window procedure as if running within a native
Presentation Manager application. The application window procedure can find the
PRESSPACE window procedure by calling WinQueryWindowPtr() with offset
BLKBOX_WINPROC and using the handle of the PRESSPACE object.
(WinDefWindowProc() should not be used.)

When an ASL event is generated which requires the subprocedure to carry out
some action, the SEND or POST actions are used to have a Presentation Manager
message routed to the subprocedure.

When the subprocedure receives a message which requires some action from ASL,
the subprocedure sends a BB_SIGNAL message to the default window procedure. The
system processes this message by raising an ASL SIGNAL event.


ΓòÉΓòÉΓòÉ 146. PRINTER ΓòÉΓòÉΓòÉ

The PRINTER object class provides access to printers configured for use by the
operating system. The object can be opened by direct manipulation (dragging an
object to the printer) or from within ASL by using the SYSTEM'PRINTREQUEST()
action.

Attributes

Actions

Events: None.

More about PRINTER

Examples

See also: SYSTEM, LINE(), PAGE(), POSITION(), SPACE(), TAB()


ΓòÉΓòÉΓòÉ 146.1. Attributes ΓòÉΓòÉΓòÉ

DIALOG                 ORIGINATOR
CODE                   DESCRIPTION
COPIES                 WIDTH
HEIGHT                 COLOR


ΓòÉΓòÉΓòÉ 146.1.1. DIALOG ΓòÉΓòÉΓòÉ

Used to determine whether the SETTINGS() action is called. If the PRINT event
was triggered by direct manipulation, or by Print from the icon context menu,
then Dialog reflects the current value of the "Job dialog before print" setting
on the Workplace Shell printer. If the PRINT event was triggered by
PRINTREQUEST, then it reflects the Dialog parameter.

Default: 1 Call SETTINGS()


ΓòÉΓòÉΓòÉ 146.1.2. ORIGINATOR ΓòÉΓòÉΓòÉ

If the PRINT event was triggered by direct manipulation (dragging), then
ORIGINATOR identifies the SOURCECTRL object that facilitated the drop on the
printer. Otherwise, ORIGINATOR is NULL.


ΓòÉΓòÉΓòÉ 146.1.3. CODE ΓòÉΓòÉΓòÉ

Most recent operating system or internal error code.

Default: Set by any action involving the printer.


ΓòÉΓòÉΓòÉ 146.1.4. DESCRIPTION ΓòÉΓòÉΓòÉ

Job description string. Displayed in the printer queue to identify the job. Set
on OPEN, then read-only.

Default: None.


ΓòÉΓòÉΓòÉ 146.1.5. COPIES ΓòÉΓòÉΓòÉ

Number of copies to print. Set on OPEN, then read-only. Use the SETTINGS action
to modify the number of copies.

Default: 1


ΓòÉΓòÉΓòÉ 146.1.6. WIDTH ΓòÉΓòÉΓòÉ

Width in millimeters of the paper in the printer.


ΓòÉΓòÉΓòÉ 146.1.7. HEIGHT ΓòÉΓòÉΓòÉ

Height in millimeters of the paper in the printer.


ΓòÉΓòÉΓòÉ 146.1.8. COLOR ΓòÉΓòÉΓòÉ

Queried from the current printer.

0  Monochrome printer (default), and

1  Color printer.


ΓòÉΓòÉΓòÉ 146.2. Actions ΓòÉΓòÉΓòÉ

PUT()                 SETTINGS()


ΓòÉΓòÉΓòÉ 146.2.1. PUT() ΓòÉΓòÉΓòÉ

             <ΓöÇ,ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöÇΓöÇPUT(exp1ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼Γö┤ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
              ΓööΓöÇexp2ΓöÇΓöÿ

Prints the string resulting from an expression. As many expressions exp2 to
expn as wanted to be printed can be supplied as arguments to PUT(), separated
by commas. This action is similar to FILE'PUT() - see More about FILE'PUT for
details.


ΓòÉΓòÉΓòÉ 146.2.2. SETTINGS() ΓòÉΓòÉΓòÉ

                   ΓöîΓöÇ1ΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöÇΓöÇSETTINGS(name,ΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                   ΓööΓöÇtypeΓöÇΓöÿ

This action presents a modal dialog to allow certain printer options to be set.
It returns a value of 1 (true) if the user selects Print on the dialog. It
returns a value of 0 (false) if the user closes the dialog by any other means.

If specified, name must match the instance name of the calling application. It
is used to construct the title of any displayed dialogs.

Calling SETTINGS after data has been submitted to the printer will generate an
error.

If specified, type may have one of three numeric values:

1         (Default) Provides the default dialog allowing Copies to be set, as
          well as allowing navigation to the device driver specific Job Options
          dialog (by using an Options button). This will effectively reset all
          printer settings and replace them either with the default settings,
          or with the ones in the Job Options dialog.
2         Provides a dialog allowing an available nonproportional font to be
          selected.
3         Provides a dialog allowing an available nonproportional or
          proportional font to be selected.

When you select a font using a type 2 or type 3 dialog, all text sent to the
printer by the PUT action is printed in the selected font. Graphical output is
not affected.


ΓòÉΓòÉΓòÉ 146.3. More about PRINTER ΓòÉΓòÉΓòÉ

o If you are going to plot charts, the PMPLOT queue driver is recommended.
  Plotting is possible with the default PMPRINT driver, however hidden lines
  and surfaces will not be removed from the charts.

o The output expression for PUT() can be formatted using the SPACE(), LINE(),
  and PAGE() functions.

o If a PUT() expression is a reference to a vector with index 0, then all the
  elements of the array are concatenated and printed.

o The PRINTREQUEST action in the SYSTEM object causes a PRINT event to occur.
  The parameters for printing can be set from this event.


ΓòÉΓòÉΓòÉ 146.4. Examples ΓòÉΓòÉΓòÉ

Refer to the PRINT.PRG program supplied in Development Samples for a detailed
example using the PRINTER object.

Examples source library:


ΓòÉΓòÉΓòÉ 147. PROCEDURE ΓòÉΓòÉΓòÉ

The PROCEDURE statement associates a name with a statement or block of
statements. A procedure can be called using the CALL statement, or directly as
a function.

ΓöÇΓöÇPROCEDUREΓöÇΓöÇprocedureΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                          Γöé    <ΓöÇ,ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ    Γöé
                          ΓööΓöÇ(ΓöÇΓöÇΓöÇΓöÇparameterΓöÇΓö┤ΓöÇΓöÇ)ΓöÇΓöÿ

Examples

More about PROCEDURE

See also: CALL, DECLARE, LEAVE, LIBRARY ASL, LIBRARY DLL, LIBRARY REXX,
LIBRARY ENTRY, LIBRARY LOCAL, PROCEDURE(), RETURN


ΓòÉΓòÉΓòÉ 147.1. Examples ΓòÉΓòÉΓòÉ

DECLARE POINTER dispatch = PROCEDURE("Decode_Seq_No")
Current_Seq_No = 1 + (?dispatch) (Last_Seq_No)

CALL UPDATE(DataBuffer)                 ! Called as procedure.

Price = MARKUP(Cost)                    ! Invoked as function.

PROCEDURE UPDATE(RecBuf)
DO
  DECLARE CHAR[*] RecBuf

  CALL Opfil'PUT(RecBuf)
  Status = "New"
  Action = ""
  ...
END

PROCEDURE MarkUp(Value)
DO
  DECLARE NUMERIC Value
  RETURN (Value * 1.375)
END

PROCEDURE Decode_Seq_No(Num)
DO
  DECLARE NUMERIC Num
  ...
END

Examples source library:


ΓòÉΓòÉΓòÉ 147.2. More about PROCEDURE ΓòÉΓòÉΓòÉ

o If a procedure contains more than one statement, the statements must be
  enclosed in a DO...END block.

o The number of parameters used when the procedure is called or invoked as a
  function must normally match the number of parameters on the PROCEDURE
  statement. This restriction does not apply to indirect procedure calls using
  procedure pointers. In this case, parameter lists are truncated or extended
  with NULL values as necessary.

o On an indirect procedure call using a procedure pointer, the parameter list
  parentheses are required, even if there are no parameters. Parentheses are
  also required around the procedure reference to allow for the lower level of
  precedence of the indirection operator  ?.

o Unless they are declared, variables are not local to a procedure.

o When a procedure is invoked as a function, a value is returned to the calling
  code using a RETURN statement. RETURN has two effects: it ends execution of
  the procedure and, optionally, returns a value.

o If a procedure is given the same name as a system function, the system
  function cannot be called.

o PROCEDURE statements can also be held in a LIBRARY.


ΓòÉΓòÉΓòÉ 148. PROCEDURE() ΓòÉΓòÉΓòÉ

The PROCEDURE() function returns a pointer to a procedure.

ΓöÇΓöÇPROCEDURE(procedurename)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Examples

More about PROCEDURE()

See also: CALL, LIBRARY LOCAL, PROCEDURE


ΓòÉΓòÉΓòÉ 148.1. Examples ΓòÉΓòÉΓòÉ

LET dispatch = PROCEDURE("SelectMainOK")
CALL (?dispatch)()

Examples source library:


ΓòÉΓòÉΓòÉ 148.2. More about PROCEDURE() ΓòÉΓòÉΓòÉ

o The procedure may be in the same source program as the PROCEDURE() invocation
  or be named on a LIBRARY ASL, LIBRARY DLL, or LIBRARY REXX statement.

o Unless a LIBRARY LOCAL statement is used, PROCEDURE() can be used for any
  local procedure.

o The data type of the result from PROCEDURE() is POINTER.


ΓòÉΓòÉΓòÉ 149. PROFILE ΓòÉΓòÉΓòÉ

The PROFILE object class gives access to various properties of the Visualizer
and OS/2 environments. The attributes of the PROFILE object are all read-only.

Attributes

Subobjects

Actions: None.

Events: None.

Examples

More about PROFILE


ΓòÉΓòÉΓòÉ 149.1. Attributes ΓòÉΓòÉΓòÉ

BGCOLOR                  CODEPAGE
CODEPAGETYPE             CURRENCY
DATE                     DATEFORMAT
DATESEPAR                DBCSFONT
DECSEPAR                 DSSDIR
DSSPATH                  EXE
FGCOLOR                  HILITEBGCOLOR
HILITEFGCOLOR            INSTANCE
LANGUAGE                 MAIL
PCS                      PLACES
RELATIONAL               REPLACE
SHORTDATE                SRPI
THOUSEPAR                TIME
TIMEFORMAT               TIMESEPAR
VERSION


ΓòÉΓòÉΓòÉ 149.1.1. BGCOLOR ΓòÉΓòÉΓòÉ

Background color. Integer in the range 0-17. See Colors and color codes for
details of colors available.


ΓòÉΓòÉΓòÉ 149.1.2. CODEPAGE ΓòÉΓòÉΓòÉ

PC code page.


ΓòÉΓòÉΓòÉ 149.1.3. CODEPAGETYPE ΓòÉΓòÉΓòÉ

OS/2 operating environment.

0         Single-byte character set version of OS/2
1         Double-byte character set version of OS/2


ΓòÉΓòÉΓòÉ 149.1.4. CURRENCY ΓòÉΓòÉΓòÉ

Currency symbol.


ΓòÉΓòÉΓòÉ 149.1.5. DATE ΓòÉΓòÉΓòÉ

Current date.


ΓòÉΓòÉΓòÉ 149.1.6. DATEFORMAT ΓòÉΓòÉΓòÉ

Formal date format.


ΓòÉΓòÉΓòÉ 149.1.7. DATESEPAR ΓòÉΓòÉΓòÉ

Date separator.


ΓòÉΓòÉΓòÉ 149.1.8. DBCSFONT ΓòÉΓòÉΓòÉ

Indicates whether DBCS outline fonts are available.

0         No DBCS outline font available.
1         DBCS outline font available.


ΓòÉΓòÉΓòÉ 149.1.9. DECSEPAR ΓòÉΓòÉΓòÉ

Decimal separator.


ΓòÉΓòÉΓòÉ 149.1.10. DSSDIR ΓòÉΓòÉΓòÉ

The name of the directory where Visualizer stores output files. The value of
this attribute is taken from the FTB1DIR environment variable, which is set in
the OS/2 CONFIG.SYS file by the SET FTB1DIR = statement.

Default: None


ΓòÉΓòÉΓòÉ 149.1.11. DSSPATH ΓòÉΓòÉΓòÉ

The search path used to locate the Visualizer system files. The value of this
attribute is taken from the FTB1PATH environment variable, which is set in the
OS/2 CONFIG.SYS file by the SET FTB1PATH = statement.

Default: None


ΓòÉΓòÉΓòÉ 149.1.12. EXE ΓòÉΓòÉΓòÉ

Name of the .EXE file that is currently executing Visualizer.


ΓòÉΓòÉΓòÉ 149.1.13. FGCOLOR ΓòÉΓòÉΓòÉ

Foreground color. Integer in the range 0-17. See Colors and color codes for
details of colors available.


ΓòÉΓòÉΓòÉ 149.1.14. HILITEBGCOLOR ΓòÉΓòÉΓòÉ

Highlight background color. Integer in the range 0-17. See
Colors and colorcodes for details of colors available.


ΓòÉΓòÉΓòÉ 149.1.15. HILITEFGCOLOR ΓòÉΓòÉΓòÉ

Highlight foreground color. Integer in the range 0-17. See
Colors and colorcodes for details of colors available.


ΓòÉΓòÉΓòÉ 149.1.16. INSTANCE ΓòÉΓòÉΓòÉ

The current instance of Visualizer.


ΓòÉΓòÉΓòÉ 149.1.17. LANGUAGE ΓòÉΓòÉΓòÉ

Code for language used. A three-letter string:

"CHT"  Traditional Chinese
"DEU"  German
"ENU"  US English
"ESP"  Spanish
"FRA"  French
"JPN"  Japanese
"KOR"  Korean
"NLD"  Dutch


ΓòÉΓòÉΓòÉ 149.1.18. MAIL ΓòÉΓòÉΓòÉ

Whether a mail system is installed.

0         No mail system installed
1         Mail system installed


ΓòÉΓòÉΓòÉ 149.1.19. PCS ΓòÉΓòÉΓòÉ

Check for the presence of AS/400 DLL.


ΓòÉΓòÉΓòÉ 149.1.20. PLACES ΓòÉΓòÉΓòÉ

Number of decimal places displayed.


ΓòÉΓòÉΓòÉ 149.1.21. RELATIONAL ΓòÉΓòÉΓòÉ

Check for the presence of a database manager.

0         No database manager installed
1         Database manager installed


ΓòÉΓòÉΓòÉ 149.1.22. REPLACE ΓòÉΓòÉΓòÉ

Display warning prompt before replacing file.

0         No warning prompt
1         Warning prompt displayed

Default: 1 (Warning displayed)


ΓòÉΓòÉΓòÉ 149.1.23. SHORTDATE ΓòÉΓòÉΓòÉ

Short date format.


ΓòÉΓòÉΓòÉ 149.1.24. SRPI ΓòÉΓòÉΓòÉ

Check for the presence of host communication DLL.


ΓòÉΓòÉΓòÉ 149.1.25. THOUSEPAR ΓòÉΓòÉΓòÉ

Thousands separator.


ΓòÉΓòÉΓòÉ 149.1.26. TIME ΓòÉΓòÉΓòÉ

Current time.


ΓòÉΓòÉΓòÉ 149.1.27. TIMEFORMAT ΓòÉΓòÉΓòÉ

Time format.


ΓòÉΓòÉΓòÉ 149.1.28. TIMESEPAR ΓòÉΓòÉΓòÉ

Time separator.


ΓòÉΓòÉΓòÉ 149.1.29. VERSION ΓòÉΓòÉΓòÉ

Version number of Visualizer.


ΓòÉΓòÉΓòÉ 149.2. Subobjects ΓòÉΓòÉΓòÉ

PROFILE objects have subobjects. These subobjects represent the verbal forms
for the following items:

o Days of the week
o Month names
o Short (three-letter) forms of month names
o The suffixes for the first 31 ordinal numbers.

The actual content of these subobject vectors depends on the country setup of
your computer.

DAYNAMES[7]         Names of the days of the week
MONTHNAMES[12]      Names of the months
MONTH3CHAR[12]      First three characters of the names of the months
ORDINALS[31]        The suffixes for the first 31 ordinal numbers (st for 1st,
                    nd for 2nd, rd for 3rd, and so forth).

All the subobjects have one read-only attribute, NAME, which can be retrieved
in the following way:

OPEN PROFILE profs
LET Today = T.profs.daynames[x]'NAME
         ! If x = 3, then Today is now set to 'Wednesday'

where:

x         is the required subscript.


ΓòÉΓòÉΓòÉ 149.3. Examples ΓòÉΓòÉΓòÉ

! The profile object gives access to system level settings
!
PROCEDURE PROFILE
DO
  DECLARE NUMERIC i
  ! all attributes of the profile object are read only
  OPEN profile prof
  !
  ! use the profile sub-objects to create some data
  ! arrays for later use as reference arrays
  DEFINE days[0]
  DEFINE array1[0]
  DEFINE array2[0]
  DO i=1:7
    ! create a list of day names
    INSERT days[0]=t.prof.daynames[i]'NAME
  END
  DO i=1:12
    ! a list of month names
    INSERT array1[0]=t.prof.monthnames[i]'NAME
    ! a list of abbreviated month names
    INSERT array2[0]=t.prof.month3char[i]'NAME
  END
END

Examples source library:


ΓòÉΓòÉΓòÉ 149.4. More about PROFILE ΓòÉΓòÉΓòÉ

All subobjects of PROFILE are opened automatically as subobject instances when
the PROFILE object is opened.


ΓòÉΓòÉΓòÉ 150. PUSH ΓòÉΓòÉΓòÉ

The PUSH object class creates an instance of a push button.

Attributes

Actions

Events

Examples

More about PUSH


ΓòÉΓòÉΓòÉ 150.1. Attributes ΓòÉΓòÉΓòÉ

BITMAP                CLONEDIR
CLONEGAP              CLONES
DEFAULT               ENABLED
EXPRESSION            HELP
HANDLES               HELPBUTTON
ORIGIN                SCALED
SIZEX                 SIZEY
TEXT                  VISIBLE
X                     Y


ΓòÉΓòÉΓòÉ 150.1.1. BITMAP ΓòÉΓòÉΓòÉ

This attribute is a character string of up to 255 bytes that specifies the
bitmap to be displayed on the button. It may specify either a file containing a
bitmap, or a DLL and resource identifier for a bitmap.

If the string contains the "<>" symbols, then the string is assumed to be in
the form DLLName<ResourceID>. Otherwise, the string is assumed to hold a fully
qualified file name. (Such a file name can be constructed from the NAME and
LOCATION attributes of a STREAM based object, to allow the bitmap to be
retrieved from an SMEMORY or SFILE object.)

If this attribute has a value, then any prior TEXT attribute setting is ignored
and the bitmap is be used for the button. If the TEXT attribute is subsequently
modified, then the TEXT value has precedence over the value of this attribute.
(You cannot identify a bitmap by using the EXPRESSION attribute.)

The term bitmap refers to any format supported by the GRAPHIC'BITMAP() action
(OS/2 BITMAP, PCX, TIFF, and GIF). The bitmap format is converted before use,
if necessary.

Default: None Set on OPEN, then read-only.


ΓòÉΓòÉΓòÉ 150.1.2. CLONEDIR ΓòÉΓòÉΓòÉ

Which way the clones are to be laid out relative to the original:

1         Down
2         Up
3         Left
4         Right

Set on OPEN, then read-only.

Default: 1 (Down)


ΓòÉΓòÉΓòÉ 150.1.3. CLONEGAP ΓòÉΓòÉΓòÉ

Space between clones, in dialog units.

Set on OPEN, then read-only.

Default: 0


ΓòÉΓòÉΓòÉ 150.1.4. CLONES ΓòÉΓòÉΓòÉ

Number of clones to be displayed.

Set on OPEN, then read-only.

Default: 1


ΓòÉΓòÉΓòÉ 150.1.5. DEFAULT ΓòÉΓòÉΓòÉ

Clone to be offered as a default (with cursor focus). A positive number between
1 and the total number of clones.

Default: 1


ΓòÉΓòÉΓòÉ 150.1.6. DISABLED ΓòÉΓòÉΓòÉ

Bitmap that is displayed on the button when it is disabled (grayed out).
Details of this attribute are the same as for the BITMAP attribute.

Default: None


ΓòÉΓòÉΓòÉ 150.1.7. DOWN ΓòÉΓòÉΓòÉ

Bitmap that is displayed on the button when it is down (pushed). Details of
this attribute are the same as for the BITMAP attribute.

Default: None


ΓòÉΓòÉΓòÉ 150.1.8. ENABLED ΓòÉΓòÉΓòÉ

Whether the push button is enabled:

0         Push button grayed out and not selectable
1         Push button enabled

Default: 1 (Enabled)


ΓòÉΓòÉΓòÉ 150.1.9. EXPRESSION ΓòÉΓòÉΓòÉ

Pointer to a variable, the contents of which are displayed with the push
button.

Note that the TEXT and EXPRESSION attributes are mutually exclusive.

Default: ""


ΓòÉΓòÉΓòÉ 150.1.10. HELP ΓòÉΓòÉΓòÉ

Resource identifier of the full help text for the push button.

Default: 0


ΓòÉΓòÉΓòÉ 150.1.11. HANDLES ΓòÉΓòÉΓòÉ

Whether sizing handles are attached to the push button to support moving,
sizing, and copying operations. These direct manipulation techniques follow the
CUA guidelines. See also the AUTOSELECT attribute of the WINDOW object.

0         Handles are not displayed
1         Handles are displayed

Default: 0 (No handles)


ΓòÉΓòÉΓòÉ 150.1.12. HELPBUTTON ΓòÉΓòÉΓòÉ

The clone for the help push button (allowing direct access to the Information
Presentation Facility Help Manager). An integer no greater than the total
number of clones.

Default: 0


ΓòÉΓòÉΓòÉ 150.1.13. LATCHABLE ΓòÉΓòÉΓòÉ

Whether the push button is latchable.

0         Not latchable-the state changes to DOWN when the button is pushed,
          then returns to UP when the button is released.
1         Latchable-the state changes to DOWN when the button is pushed, then
          stays DOWN until the button is pushed again.

Default: 0 (Not latchable)


ΓòÉΓòÉΓòÉ 150.1.14. ORIGIN ΓòÉΓòÉΓòÉ

The corner of the enclosing window to be taken as the origin. The position of
the push button is measured from this point.

"TL"      Top left
"TR"      Top right
"BL"      Bottom left
"BR"      Bottom right

Default: "BL" (Bottom left)


ΓòÉΓòÉΓòÉ 150.1.15. SCALED ΓòÉΓòÉΓòÉ

This Boolean value indicates that the bitmap will be scaled to fit the push
button (when 1) or will be clipped to fit (when 0).

Default: 0 (Not scaled)


ΓòÉΓòÉΓòÉ 150.1.16. STATE ΓòÉΓòÉΓòÉ

The current state of the button:

"UP"      Enabled, but not pushed
"DOWN"    Pushed
"DISABLED" Not enabled (grayed out)

Default: "UP"


ΓòÉΓòÉΓòÉ 150.1.17. SIZEX ΓòÉΓòÉΓòÉ

Width, in dialog units.

Default: 0


ΓòÉΓòÉΓòÉ 150.1.18. SIZEY ΓòÉΓòÉΓòÉ

Height, in dialog units.

Default: 0


ΓòÉΓòÉΓòÉ 150.1.19. TEXT ΓòÉΓòÉΓòÉ

Text string displayed on the push button.

Note that the TEXT and EXPRESSION attributes are mutually exclusive.

Default: ""


ΓòÉΓòÉΓòÉ 150.1.20. UP ΓòÉΓòÉΓòÉ

Bitmap that is displayed on the button when it is up (not pushed). Details of
this attribute are the same as for the BITMAP attribute.

Default: None


ΓòÉΓòÉΓòÉ 150.1.21. VISIBLE ΓòÉΓòÉΓòÉ

Whether the push button is displayed:

0         Push button not displayed
1         Push button displayed

Default: 1 (Displayed)


ΓòÉΓòÉΓòÉ 150.1.22. X ΓòÉΓòÉΓòÉ

Horizontal position within the window, in dialog units.

Default: 0


ΓòÉΓòÉΓòÉ 150.1.23. Y ΓòÉΓòÉΓòÉ

Vertical position within the window, in dialog units.

Default: 0


ΓòÉΓòÉΓòÉ 150.2. Actions ΓòÉΓòÉΓòÉ

REFRESH()


ΓòÉΓòÉΓòÉ 150.2.1. REFRESH() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇREFRESH()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Forces repainting of the push button on screen.


ΓòÉΓòÉΓòÉ 150.3. Events ΓòÉΓòÉΓòÉ

DESKTOP            SELECT


ΓòÉΓòÉΓòÉ 150.3.1. DESKTOP ΓòÉΓòÉΓòÉ

Signaled when the push button is moved, sized, or copied. A.System.Operation is
set to "MOVE", "SIZE", or "COPY". A.System.Object contains the name of the
control.


ΓòÉΓòÉΓòÉ 150.3.2. SELECT ΓòÉΓòÉΓòÉ

Signaled when the push button is selected. A.System.Object is set to name of
the push button. A.System.Boxnumber is set to the number of the clone selected.


ΓòÉΓòÉΓòÉ 150.4. Examples ΓòÉΓòÉΓòÉ

! Sample code which dynamically opens a set of push buttons.
! A set of 5 buttons is opened,placed vertically on the
! window. Examples of how to manipulate the controls are also
! provided.
PROCEDURE PUSH
DO
  OPEN push push1,SampWind,
   X     = 70, Y     = 150,         ! control position
   SIZEX = 60, SIZEY = 12,          ! control size
   EXPRESSION = "Days[1]",          ! reference to the text to be displayed
   CLONES = 5,                      ! 5 clones required (default 1)
   CLONEDIR = 1,                    ! 1=down (the default)
   CLONEGAP = 5
  !
  ! set the default button to the fourth clone
  !
  LET push1'default[0] = 4
  !
  ! gray the third clone
  !
  LET push1'enabled[3] = 0
  !
  ! dynamically reposition the fifth clone 10 dbu to the right of
  ! its current position
  !
  LET push1'x[5] = push1'x[5] + 10
END

Examples source library:


ΓòÉΓòÉΓòÉ 150.5. More about PUSH ΓòÉΓòÉΓòÉ

o The following attributes can only be modified for the entire clone set, not
  for the individual clones:

   CLONEDIR
   CLONEGAP
   DEFAULT
   HANDLES
   HELPBUTTON
   ORIGIN
   VISIBLE

To modify an attributes for a the entire clone set, use a reference of zero:

LET MyPush[0]'VISIBLE = 0
The set reference of zero must be used even when the push button does not have
any clones.


ΓòÉΓòÉΓòÉ 151. QUEUE PROGRAM ΓòÉΓòÉΓòÉ

The QUEUE PROGRAM statement signals an event to an active program. The request
is queued for execution until the program that sent the QUEUE PROGRAM has
reached a wait state.

ΓöÇΓöÇQUEUEΓöÇΓöÇPROGRAMΓöÇΓöÇprogramaliasΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
   ΓööΓöÇ,eventkeywordΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÿ
                   Γöé    <ΓöÇ,ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ    Γöé
                   ΓööΓöÇ(ΓöÇΓöÇΓöÇΓöÇparameterΓöÇΓö┤ΓöÇΓöÇ)ΓöÇΓöÿ

Examples

More about QUEUE PROGRAM

See also: RUN PROGRAM, START, WAIT PROGRAM


ΓòÉΓòÉΓòÉ 151.1. Examples ΓòÉΓòÉΓòÉ

QUEUE PROGRAM graphs,SELECT(CURSEL)
QUEUE PROGRAM staff
QUEUE PROGRAM testrun,STOP

Examples source library:


ΓòÉΓòÉΓòÉ 151.2. More about QUEUE PROGRAM ΓòÉΓòÉΓòÉ

o Many programs can be queued for execution at one time. Queued programs are
  executed in first in, first out (FIFO) order.

o The application does not enter a wait state until all queued events have been
  processed.

o The number of parameters passed by QUEUE PROGRAM need not match the parameter
  list on the ON statement. NULL values are supplied as required.


ΓòÉΓòÉΓòÉ 152. RADIANS() ΓòÉΓòÉΓòÉ

The RADIANS() function converts a value specified in degrees to radians.

ΓöÇΓöÇRADIANS(degrees)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Examples

See also: DEGREES()


ΓòÉΓòÉΓòÉ 152.1. Examples ΓòÉΓòÉΓòÉ

x = RADIANS(57.2957795130823)  !  Result is 1
x = RADIANS(180)               !  Result is 3.141592653589793

Examples source library:


ΓòÉΓòÉΓòÉ 153. RADIO ΓòÉΓòÉΓòÉ

The RADIO object class creates an instance of a radio button.

Parent: WINDOW

Attributes

Actions

Events

Examples

More about RADIO


ΓòÉΓòÉΓòÉ 153.1. Attributes ΓòÉΓòÉΓòÉ

BGCOLOR               CHECKED
CLONEDIR              CLONEGAP
CLONES                ENABLED
EXPRESSION            FGCOLOR
HANDLES               HELP
ORIGIN                SIZEX
SIZEY                 TEXT
VISIBLE               X
Y


ΓòÉΓòÉΓòÉ 153.1.1. BGCOLOR ΓòÉΓòÉΓòÉ

Background color. Integer in the range 1-19. See Colors and color codes for
details of colors available.

Default: System window background color


ΓòÉΓòÉΓòÉ 153.1.2. CHECKED ΓòÉΓòÉΓòÉ

Clone number selected.

Default: 1


ΓòÉΓòÉΓòÉ 153.1.3. CLONEDIR ΓòÉΓòÉΓòÉ

Direction, relative to the original, in which the clones are laid out:

1         Down
2         Up
3         Left
4         Right

Set on OPEN, then read-only.

Default: 1 (Down)


ΓòÉΓòÉΓòÉ 153.1.4. CLONEGAP ΓòÉΓòÉΓòÉ

Space between clones, in dialog box units.

Set on OPEN, then read-only.

Default: 0


ΓòÉΓòÉΓòÉ 153.1.5. CLONES ΓòÉΓòÉΓòÉ

Number of clones.

Set on OPEN, then read-only.

Default: 1


ΓòÉΓòÉΓòÉ 153.1.6. ENABLED ΓòÉΓòÉΓòÉ

Whether the radio button is enabled:

0         Radio button grayed out and not selectable
1         Radio button enabled

Default: 1 (Enabled)


ΓòÉΓòÉΓòÉ 153.1.7. EXPRESSION ΓòÉΓòÉΓòÉ

Pointer to a variable, the contents of which are displayed with the radio
button.

Note that the TEXT and EXPRESSION attributes are mutually exclusive.

Default: ""


ΓòÉΓòÉΓòÉ 153.1.8. FGCOLOR ΓòÉΓòÉΓòÉ

Foreground color. Integer in the range 1-19. See Colors and color codes for
details of colors available.

Default: System window text color


ΓòÉΓòÉΓòÉ 153.1.9. HANDLES ΓòÉΓòÉΓòÉ

Whether sizing handles are attached to the radio button to support moving,
sizing, and copying operations. These direct manipulation techniques follow the
CUA guidelines. See also the AUTOSELECT attribute of the WINDOW object.

0         Handles are not displayed
1         Handles are displayed

Default: 0 (No handles)


ΓòÉΓòÉΓòÉ 153.1.10. HELP ΓòÉΓòÉΓòÉ

Resource identifier (res ID) of the full help text for this radio button.

Default: 0


ΓòÉΓòÉΓòÉ 153.1.11. ORIGIN ΓòÉΓòÉΓòÉ

The corner of the enclosing window is to be taken as the origin. The position
of the radio button is measured from this point.

"TL"      Top left
"TR"      Top right
"BL"      Bottom left
"BR"      Bottom right

Default: "BL" (Bottom left)


ΓòÉΓòÉΓòÉ 153.1.12. SIZEX ΓòÉΓòÉΓòÉ

Width, in dialog box units.

Default: 0


ΓòÉΓòÉΓòÉ 153.1.13. SIZEY ΓòÉΓòÉΓòÉ

Height, in dialog box units.

Default: 0


ΓòÉΓòÉΓòÉ 153.1.14. TEXT ΓòÉΓòÉΓòÉ

Text string to appear alongside the radio button.

Note that the TEXT and EXPRESSION attributes are mutually exclusive.

Default: ""


ΓòÉΓòÉΓòÉ 153.1.15. VISIBLE ΓòÉΓòÉΓòÉ

Whether the radio button is displayed:

0         Radio button not displayed
1         Radio button displayed

Default: 1 (Displayed)


ΓòÉΓòÉΓòÉ 153.1.16. X ΓòÉΓòÉΓòÉ

Horizontal position within the window, in dialog box units.

Default: 0


ΓòÉΓòÉΓòÉ 153.1.17. Y ΓòÉΓòÉΓòÉ

Vertical position within the window, in dialog units.

Default: 0


ΓòÉΓòÉΓòÉ 153.2. Actions ΓòÉΓòÉΓòÉ

REFRESH()


ΓòÉΓòÉΓòÉ 153.2.1. REFRESH() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇREFRESH()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Forces repainting of the radio button on screen.


ΓòÉΓòÉΓòÉ 153.3. Events ΓòÉΓòÉΓòÉ

DESKTOP            SELECT


ΓòÉΓòÉΓòÉ 153.3.1. DESKTOP ΓòÉΓòÉΓòÉ

Signaled when the radio button is moved, sized, or copied. A.System.Operation
is set to "MOVE", "SIZE", or "COPY". A.System.Object contains the name of the
control.


ΓòÉΓòÉΓòÉ 153.3.2. SELECT ΓòÉΓòÉΓòÉ

Signals the ON SELECT block. A.System.Object is set to the name of the radio
button. A.System.Boxnumber is set to the number of the clone selected.


ΓòÉΓòÉΓòÉ 153.4. Examples ΓòÉΓòÉΓòÉ

!
! Sample of the RADIO object.
! This sample demonstrates both how to open the control and also
! how to select an individual item and how to gray an item.
!
PROCEDURE RADIO
DO
  OPEN RADIO Radio1,SampWind,
   X     = 70, Y     = 150,         ! position on window
   SIZEX = 70, SIZEY = 12,          ! size
   EXPRESSION = 'days[1]',          ! vector to use as display text
   CLONES = 5,                      ! number of radio buttons
   CLONEDIR = 1,                    ! direction 1=down (default)
   clonegap = 5                     ! space between buttons
  !
  ! since only one radio button of a set may be checked, the
  ! syntax implies this by setting check at the zero clone level
  LET Radio1[0]'CHECKED = 4
  !
  ! more than on radio button may, however, be gray. You therefore
  ! set this at the individual clone level
  LET Radio1[3]'ENABLED = 0         ! disable (gray) the third button
END

Examples source library:


ΓòÉΓòÉΓòÉ 153.5. More about RADIO ΓòÉΓòÉΓòÉ

o The following attributes can only be modified for the entire clone set, not
  for the individual clones:

   BGCOLOR
   CHECKED
   CLONEDIR
   CLONEGAP
   FGCOLOR
   HANDLES
   VISIBLE

o RADIO is only really useful as a cloned set, a CHECKBOX should be used in
  preference to a single RADIO button.


ΓòÉΓòÉΓòÉ 154. RANDOM() ΓòÉΓòÉΓòÉ

The RANDOM() function returns a pseudo-random positive number.

            ΓöîΓöÇ0ΓöÇΓöÇΓöÇΓöÉ   ΓöîΓöÇ999ΓöÇΓöÉ
ΓöÇΓöÇRANDOM(ΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇ,ΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇ,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
            ΓööΓöÇminΓöÇΓöÿ   ΓööΓöÇmaxΓöÇΓöÿ   ΓööΓöÇseedΓöÇΓöÿ

Examples

More about RANDOM()


ΓòÉΓòÉΓòÉ 154.1. Examples ΓòÉΓòÉΓòÉ

x = RANDOM()
x = RANDOM(78,94)
x = RANDOM(,,645)

Examples source library:


ΓòÉΓòÉΓòÉ 154.2. More about RANDOM() ΓòÉΓòÉΓòÉ

o The range for seed is 0 to 65535. Negative numbers are not accepted.

o To get a predictable sequence of pseudo-random numbers, use RANDOM() several
  times but only specify seed on the first.

o The number generator is global for a task.  The current seed is saved for
  each task.


ΓòÉΓòÉΓòÉ 155. RECTANGLE ΓòÉΓòÉΓòÉ

The RECTANGLE graphics primitive object class creates an instance of a
rectangle.

Parent: DEFINE

Attributes

Actions: None.

Events: None.

Examples


ΓòÉΓòÉΓòÉ 155.1. Attributes ΓòÉΓòÉΓòÉ

REFERENCE

The following standard graphics attributes are also available. They are
described in Standard graphics attributes

BOUNDED                FILLCOLOR
LINEWIDTH              SELECTED
COLOR                  FILLPATTERN
MIX                    VISIBLE
CONSTANT               LINESTYLE
SELECTABLE


ΓòÉΓòÉΓòÉ 155.1.1. REFERENCE ΓòÉΓòÉΓòÉ

Vector defining the rectangle. This vector consists of the following elements:

1         X coordinate of the bottom left corner of the rectangle
2         Y coordinate of the bottom left corner of the rectangle
3         X coordinate of the top right corner of the rectangle
4         Y coordinate of the top right corner of the rectangle

All coordinates are in world coordinate units.

Set on OPEN, then read-only.

Default: ""


ΓòÉΓòÉΓòÉ 155.2. Examples ΓòÉΓòÉΓòÉ

!
! Example of graphic RECTANGLE object
!
PROCEDURE RECTANGLE
DO
  DEFINE rectarr[4]               ! Array defining rectangle
  LET rectarr[1]=20               ! x coord, bottom left corner
  LET rectarr[2]=40               ! y coord, bottom left corner
  LET rectarr[3]=400              ! x coord, top right corner
  LET rectarr[4]=200              ! y coord, top right corner
  OPEN RECTANGLE Rectangle, Def1,
   REFERENCE         =rectarr[0], ! Array for corners
   COLOR             =6,          ! body color (red)
   FILLCOLOR         =7,          ! Fill Color
   FILLPATTERN       =9,          ! Pattern (vertical bar)
   LINESTYLE         =1,          ! Border style
   LINEWIDTH         =5           ! Border width
END

Examples source library:


ΓòÉΓòÉΓòÉ 156. REFERENCE ΓòÉΓòÉΓòÉ

The REFERENCE object may be used to convey reference information for data
between programs.

Attributes

Actions

Events: None.

Examples

See also: DDECLIENT, DDESERVER, STREAM, SOURCECTRL, TARGETCTRL, LINK


ΓòÉΓòÉΓòÉ 156.1. Attributes ΓòÉΓòÉΓòÉ

ERASE                   SOURCETYPE
APPLICATION             TOPIC
ITEM                    LOCATION
NAME                    TEMPLOCATION
TEMPNAME


ΓòÉΓòÉΓòÉ 156.1.1. ERASE ΓòÉΓòÉΓòÉ

If ERASE is 1 (true), then the target application should erase the referenced
information when it has finished with it.

Default: 0 (False). Can be set on OPEN, then read-only.


ΓòÉΓòÉΓòÉ 156.1.2. SOURCETYPE ΓòÉΓòÉΓòÉ

It is used to qualify the source of data being referenced, indicating which
attributes carry the salient reference information. It must have one of the
following values:

DDE       indicating that this is a DDE reference, and that the APPLICATION,
          TOPIC, and ITEM attributes should be used.

FILE      indicating that this is a file reference, and that the LOCATION and
          NAME attributes should be used.


ΓòÉΓòÉΓòÉ 156.1.3. APPLICATION ΓòÉΓòÉΓòÉ

It is a string representing the name of a server application or object class.
Its value may be used to set the APPLICATION attribute of a DDECLIENT object
when attempting to establish a DDE conversation with the server.


ΓòÉΓòÉΓòÉ 156.1.4. TOPIC ΓòÉΓòÉΓòÉ

It is a string representing the topic of conversation, or instance name, of the
server. Its value may be used to set the TOPIC attribute of a DDECLIENT object
when attempting to establish a DDE conversation with the server.


ΓòÉΓòÉΓòÉ 156.1.5. ITEM ΓòÉΓòÉΓòÉ

It is a string representing a server defined item that will be rendered on
request. Its value may be used as the first argument to a REQUEST, ADVISE or
UNADVISE action on a DDECLIENT object when conversion with the server via DDE.


ΓòÉΓòÉΓòÉ 156.1.6. LOCATION ΓòÉΓòÉΓòÉ

It is a string representing the fully qualified Drive:Directory or
\\Domain\Resource\ name of a file holding data of interest.


ΓòÉΓòÉΓòÉ 156.1.7. NAME ΓòÉΓòÉΓòÉ

This attribute is a string representing the fully qualified name of a file
holding data of interest.


ΓòÉΓòÉΓòÉ 156.1.8. TEMPLOCATION ΓòÉΓòÉΓòÉ

This attribute is a string representing the fully qualified Drive:Directory or
\\Domain\Resource\ name of a temporary file holding data. (The permanent copy
of the data is referenced by the LOCATION and NAME attributes.)


ΓòÉΓòÉΓòÉ 156.1.9. TEMPNAME ΓòÉΓòÉΓòÉ

This attribute is a string representing the fully qualified name of a temporary
file holding data. (The permanent copy of the data is referenced by the
LOCATION and NAME attributes.)


ΓòÉΓòÉΓòÉ 156.2. Actions ΓòÉΓòÉΓòÉ

SAVE()            LOAD()


ΓòÉΓòÉΓòÉ 156.2.1. SAVE() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSAVE(pObject)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action is used by the application to save information from the REFERENCE
object. pObject must be a pointer to an object with STREAM behavior.


ΓòÉΓòÉΓòÉ 156.2.2. LOAD() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇLOAD(pObject)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action is used by the application to load information into the REFERENCE
object. pObject must be a pointer either to a STREAM object provided through ON
TARGET, or to the handle to a CLIPBOARD object where CF_LINK data is available
on the system clipboard.


ΓòÉΓòÉΓòÉ 156.3. Examples ΓòÉΓòÉΓòÉ

See DRAGDROP.PGM in the Development Samples folder for more details.

Examples source library:


ΓòÉΓòÉΓòÉ 157. RENAME ΓòÉΓòÉΓòÉ

The RENAME statement changes the name of a variable.

ΓöÇΓöÇRENAMEΓöÇΓöÇoldname,newnameΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Examples

More about RENAME

See also: CLEAR, COPY


ΓòÉΓòÉΓòÉ 157.1. Examples ΓòÉΓòÉΓòÉ

RENAME Profile.Password,Profile.LastPassWord
RENAME XCoord,YCoord

Examples source library:


ΓòÉΓòÉΓòÉ 157.2. More about RENAME ΓòÉΓòÉΓòÉ

o If the variable referenced by newname already exists, the variable must be
  clear.

o RENAME cannot be used with declared variables.


ΓòÉΓòÉΓòÉ 158. REPLACEGLOBAL() ΓòÉΓòÉΓòÉ

The REPLACEGLOBAL() function replaces parts of a string with global values.

                          ΓöîΓöÇ"@"ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöÇΓöÇREPLACEGLOBAL(string,ΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                          ΓööΓöÇtriggerΓöÇΓöÿ

Examples

More about REPLACEGLOBAL()

See also: EXTRACTGLOBAL(), GLOBAL()


ΓòÉΓòÉΓòÉ 158.1. Examples ΓòÉΓòÉΓòÉ

rc = GLOBAL("Month","May")
rc = GLOBAL("Year",1993)
rc = REPLACEGLOBAL("It is @Month @Year")
! It is May 1993
rc = REPLACEGLOBAL("It is @@Month")
! It is @Month
rc = REPLACEGLOBAL("It is @Month@Year")
! It is May1993
rc = REPLACEGLOBAL("It is @Month@@Year")
! It is May@Year
rc = REPLACEGLOBAL("It is @Month &Year", "@&")
! It is May 1993)

Examples source library:


ΓòÉΓòÉΓòÉ 158.2. More about REPLACEGLOBAL() ΓòÉΓòÉΓòÉ

o If the characters following a trigger do not correspond to the name of a
  global value, no replacement is done.

o The name stops at the first blank or other separator.

o The sequence @@ will produce a single @.


ΓòÉΓòÉΓòÉ 159. RETURN ΓòÉΓòÉΓòÉ

The RETURN statement is used to end a procedure or event block and, optionally,
to return a value.

ΓöÇΓöÇRETURNΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
            ΓööΓöÇexpressionΓöÇΓöÿ

Examples

More about RETURN

See also: CALL, LEAVE, ON, PROCEDURE, TERMINATE


ΓòÉΓòÉΓòÉ 159.1. Examples ΓòÉΓòÉΓòÉ

PROCEDURE FindFree(pArray)
DO
  DECLARE POINTER pArray
  DECLARE NUMERIC i
  DO i = 1 : (?pArray)[0]'ENTRIES
    IF NULL( (?pArray)[i] )
    THEN RETURN i
  END
  RETURN "Not found"
END

Examples source library:


ΓòÉΓòÉΓòÉ 159.2. More about RETURN ΓòÉΓòÉΓòÉ

o When a procedure is invoked as a function, the returned value is the value of
  the function reference.  If no RETURN is executed, a value of type NULL is
  returned.

o When a procedure is invoked using CALL, any returned value is ignored.

o RETURN returns control immediately to the program or event which called the
  procedure.

o RETURN can also be used in an ON block to end execution of the block.


ΓòÉΓòÉΓòÉ 160. RETYPE() ΓòÉΓòÉΓòÉ

The RETYPE() function returns a value with the data type of a named variable.

ΓöÇΓöÇRETYPE(expression,variable)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Examples

More about RETYPE()


ΓòÉΓòÉΓòÉ 160.1. Examples ΓòÉΓòÉΓòÉ

LET result=RETYPE(value,date)

Examples source library:


ΓòÉΓòÉΓòÉ 160.2. More about RETYPE() ΓòÉΓòÉΓòÉ

o RETYPE() uses the data type of variable, and, where appropriate, uses its
  format.

o If the conversion fails, the returned value has the same data type as
  expression.


ΓòÉΓòÉΓòÉ 161. RMVSOSI() ΓòÉΓòÉΓòÉ

The RMVSOSI() function removes Shift Out (SO) and Shift In (SI) control codes
at the boundaries of groups of DBCS characters in a string.

ΓöÇΓöÇRMVSOSI(string)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Examples

More about RMVSOSI()

See also: INSSOSI()


ΓòÉΓòÉΓòÉ 161.1. Examples ΓòÉΓòÉΓòÉ

In this example, s represents a single-byte character, D1, D2, and D3 repres
double-byte characters, > represents the SO control code, and  < represents SI.

LET string = "ssss>D1D2D3<ssss"
LET result = RMVSOSI(string)

The string result contains "ssssD1D2D3ssss".

Examples source library:


ΓòÉΓòÉΓòÉ 161.2. More about RMVSOSI() ΓòÉΓòÉΓòÉ

o The result of this function is always a string of type CHARACTER.

o The code points for the SO and SI control codes are X'0E' and X'0F'.

o This function can be used for creating a PC file from an IXF file received
  from the host environment by the OS/2 Communications Manager.


ΓòÉΓòÉΓòÉ 162. ROW() ΓòÉΓòÉΓòÉ

The ROW() function returns the relative position of a row within a table. ROW()
locates rows using key-column values.

                   ΓöîΓöÇ"="ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöÇΓöÇROW(reference,ΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                   ΓööΓöÇconditionΓöÇΓöÿ

Examples


ΓòÉΓòÉΓòÉ 162.1. Examples ΓòÉΓòÉΓòÉ

LET x=ROW(employee.name{"Smith"})
IF ROW(employee.name{"Smith"}) = 0
LET position = ROW(pf.forename{updatename,updateno},">=")

Examples source library:


ΓòÉΓòÉΓòÉ 163. RUN PROGRAM ΓòÉΓòÉΓòÉ

The RUN PROGRAM statement signals an event to the requested program
immediately. After the program being run has reached a wait state, the
initiating program continues at the next statement.

ΓöÇΓöÇRUNΓöÇΓöÇPROGRAMΓöÇΓöÇprogramaliasΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
   ΓööΓöÇ,eventkeywordΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÿ
                   Γöé    <ΓöÇ,ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ    Γöé
                   ΓööΓöÇ(ΓöÇΓöÇΓöÇΓöÇparameterΓöÇΓö┤ΓöÇΓöÇ)ΓöÇΓöÿ

Examples

More about RUN PROGRAM

See also: QUEUE PROGRAM, START, WAIT PROGRAM


ΓòÉΓòÉΓòÉ 163.1. Examples ΓòÉΓòÉΓòÉ

RUN PROGRAM graphs, ENTER
RUN PROGRAM testrun, STOP(0)

Examples source library:


ΓòÉΓòÉΓòÉ 163.2. More about RUN PROGRAM ΓòÉΓòÉΓòÉ

o RUN PROGRAM causes the immediate execution of the specified program. This
  contrasts with the QUEUE PROGRAM statement, which places the program in a
  queue for later execution.

o The number of parameters passed by RUN PROGRAM need not match the parameter
  list on the ON statement. NULL values are supplied as required.


ΓòÉΓòÉΓòÉ 164. SCAN() ΓòÉΓòÉΓòÉ

The SCAN() function scans for the presence or absence of one or more specified
characters in a character string.

                                   ΓöîΓöÇ1ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ                 ΓöîΓöÇ"="ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöÇΓöÇSCAN(expression1,expression2,ΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇ,ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇ,ΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇ
                                   ΓööΓöÇstartΓöÇΓöÿ     ΓööΓöÇendΓöÇΓöÿ     ΓööΓöÇcompareΓöÇΓöÿ
      ΓöîΓöÇ"*"ΓöÇΓöÇΓöÉ
ΓöÇΓöÇ,ΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
      ΓööΓöÇtypeΓöÇΓöÿ

Examples

More about SCAN()

See also: CSCAN()


ΓòÉΓòÉΓòÉ 164.1. Examples ΓòÉΓòÉΓòÉ

String = "The cat sat on the mat"
x = SCAN(String,"cat")                      !  Result is 5
x = SCAN(String,"at",7)                     !  Result is 10
x = SCAN(String,"cat",7)                    !  Result is 0
x = SCAN(String,"The",2,,"==")              !  Result is 0
x = SCAN(String,"The",,,"==")               !  Result is 1
x = SCAN(String,"pqrs",,,,"1")              !  Result is 9

x = SCAN("abcabcabcabcdabc","abc",,,"\=")   !  Result is 13

x = SCAN("1 3 3 4 4","3", "25", 1) !  Result is 5
         ! backscan, last 3 is at position 5 relative to left end

Examples source library:


ΓòÉΓòÉΓòÉ 164.2. More about SCAN() ΓòÉΓòÉΓòÉ

o The position returned is always relative to the start (left end) of
  expression1.

o If start is beyond the position of the last character of expression1, start
  is assigned the position of that last character.

o If the start position is greater than the end position, then a backscan is
  performed.

o If the string expression2 is not found, SCAN() returns a result of 0.

o In a DBCS environment, if start is at a DBCS second byte, the scan starts
  from the next character in the string. If end is at a DBCS first byte, the
  scan ends at the previous character in the string.


ΓòÉΓòÉΓòÉ 165. SCROLL ΓòÉΓòÉΓòÉ

The SCROLL object class provides an instance of a scroll bar.

Parent: WINDOW

Attributes

Actions

Events

Examples

More about SCROLL


ΓòÉΓòÉΓòÉ 165.1. Attributes ΓòÉΓòÉΓòÉ

DIRECTION             ENABLED
HANDLES               HELP
ORIGIN                RANGESTART
RANGEEND              SIZEX
SIZEY                 SLIDERPOS
THUMBSIZE             VISIBLE
X                     Y


ΓòÉΓòÉΓòÉ 165.1.1. DIRECTION ΓòÉΓòÉΓòÉ

Scroll bar vertical or horizontal:

0         Vertical
1         Horizontal

Set on OPEN, then read-only.

Default: 0 (Vertical)


ΓòÉΓòÉΓòÉ 165.1.2. ENABLED ΓòÉΓòÉΓòÉ

Whether the scroll bar is enabled:

0         Scroll bar grayed out
1         Scroll bar enabled

Default: 1 (Enabled)


ΓòÉΓòÉΓòÉ 165.1.3. HANDLES ΓòÉΓòÉΓòÉ

Whether sizing handles are attached to the scroll bar to support moving,
sizing, and copying operations. These direct manipulation techniques follow the
CUA guidelines. See also the AUTOSELECT attribute of the WINDOW object.

0         Handles are not displayed
1         Handles are displayed

Default: 0 (No handles)


ΓòÉΓòÉΓòÉ 165.1.4. HELP ΓòÉΓòÉΓòÉ

Resource identifier (res ID) of the full help text for this scroll bar.

Default: 0


ΓòÉΓòÉΓòÉ 165.1.5. ORIGIN ΓòÉΓòÉΓòÉ

The corner of the enclosing window to be taken as the origin. The position of
the scroll bar is measured from this point.

"TL"      Top left
"TR"      Top right
"BL"      Bottom left
"BR"      Bottom right

Default: "BL" (Bottom left)


ΓòÉΓòÉΓòÉ 165.1.6. RANGESTART ΓòÉΓòÉΓòÉ

Start of associated range (not less than 1).

Default: 1


ΓòÉΓòÉΓòÉ 165.1.7. RANGEEND ΓòÉΓòÉΓòÉ

End of associated range (not greater than 32767).

Default: 100


ΓòÉΓòÉΓòÉ 165.1.8. SIZEX ΓòÉΓòÉΓòÉ

Width, in dialog box units.

Default: 0


ΓòÉΓòÉΓòÉ 165.1.9. SIZEY ΓòÉΓòÉΓòÉ

Height, in dialog box units.

Default: 0


ΓòÉΓòÉΓòÉ 165.1.10. SLIDERPOS ΓòÉΓòÉΓòÉ

Position of scroll bar within the range (otherwise ignored).

Default: 1


ΓòÉΓòÉΓòÉ 165.1.11. THUMBSIZE ΓòÉΓòÉΓòÉ

Size of scroll bar slider as a proportion of the scroll range.

Default: Minimum slider size


ΓòÉΓòÉΓòÉ 165.1.12. VISIBLE ΓòÉΓòÉΓòÉ

Whether the scroll bar is displayed:

0         Scroll bar not displayed
1         Scroll bar displayed

Default: 1 (Displayed)


ΓòÉΓòÉΓòÉ 165.1.13. X ΓòÉΓòÉΓòÉ

Horizontal position within the window, in dialog box units.

Default: 0


ΓòÉΓòÉΓòÉ 165.1.14. Y ΓòÉΓòÉΓòÉ

Vertical position within the window, in dialog box units.

Default: 0


ΓòÉΓòÉΓòÉ 165.2. Actions ΓòÉΓòÉΓòÉ

REFRESH()


ΓòÉΓòÉΓòÉ 165.2.1. REFRESH() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇREFRESH()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Forces repainting of the scroll bar on screen.


ΓòÉΓòÉΓòÉ 165.3. Events ΓòÉΓòÉΓòÉ

DESKTOP            SCROLL


ΓòÉΓòÉΓòÉ 165.3.1. DESKTOP ΓòÉΓòÉΓòÉ

Signaled when the scroll bar is moved, sized, or copied. A.System.Operation is
set to "MOVE", "SIZE", or "COPY". A.System.Object is a pointer to the control.


ΓòÉΓòÉΓòÉ 165.3.2. SCROLL ΓòÉΓòÉΓòÉ

Signaled when slider position is moved and mouse button 1 is released or when
the PgDn or PgUp keys are pressed.

A.System.Object is a pointer to the scroll bar, and A.System.Scroll is set to
the type of scroll ( "L", "R", "U", "D", "H", or "V"). A.System.ScrollAmt will
be set to 1, 0, or a value in the range for the scroll bar.

If the end user selects on the arrow of the scroll bar, then A.System.ScrollAmt
will be set to 0 and A.System.Scroll will be set to "L" or "R" for a horizontal
scroll bar or "U" or "D" for a vertical scroll bar.

If the end user selects on the shaft of the scroll bar on either side of the
slider, then A.System.ScrollAmt will be set to 1 and A.System.Scroll will be
set to "L" or "R" for a horizontal scroll bar or "U" or "D" for a vertical
scroll bar.

If the end user selects and drags the slider, then A.System.ScrollAmt will be
set to the position in the range and A.System.Scroll will be set to "H" for a
horizontal scroll bar or "V" for a vertical scroll bar.


ΓòÉΓòÉΓòÉ 165.4. Examples ΓòÉΓòÉΓòÉ

! Procedure to open sample scroll controls.
PROCEDURE SCROLL
DO
  OPEN SCROLL scroll1, Win,
   X         = 10   ,   Y    = 40 ,
   SizeX     = 80   ,
   SizeY     = 10   ,
   !
   ! the following attributes are optional
   Visible    = 1   ,              ! (default)
   Enabled    = 1   ,              ! (default)
   Direction  = 1   ,              ! horizontal (default)
   !
   ! "RangeStart" and "RangeEnd" define the granularity of the
   ! control
   RangeStart = 1   ,
   RangeEnd   = 100 ,
   ! position of slider in control
   SliderPos  = 50  ,
   ThumbSize  = 25

  ! open a second scroll control, this time placed horizontally
  !
  OPEN SCROLL scroll2, Win,
   X = 10, Y = 20 ,
   SizeX      = 10   ,
   SizeY      = 80   ,
   Direction  = 0    ,             ! vertical
   RangeStart = 1    ,
   RangeEnd   = 100  ,
   SliderPos  = 250  ,
   ThumbSize  = 25
END

Examples source library:


ΓòÉΓòÉΓòÉ 165.5. More about SCROLL ΓòÉΓòÉΓòÉ

o The SCROLL object cannot be cloned.

o Scroll bars on LIST boxes are handled automatically if present.

o Scroll bars can be added to entire windows when the WINDOW object is OPENed.


ΓòÉΓòÉΓòÉ 166. SECTOR ΓòÉΓòÉΓòÉ

The SECTOR graphics primitive object class creates an instance of a sector of a
circle.

Parent: DEFINE

Attributes

Actions: None.

Events: None.


ΓòÉΓòÉΓòÉ 166.1. Attributes ΓòÉΓòÉΓòÉ

REFERENCE              TILT

The following standard graphics attributes are also available. They are
described in Standard graphics attributes:

BOUNDED                FILLCOLOR
LINEWIDTH              SELECTED
COLOR                  FILLPATTERN
MIX                    VISIBLE
CONSTANT               LINESTYLE
SELECTABLE


ΓòÉΓòÉΓòÉ 166.1.1. REFERENCE ΓòÉΓòÉΓòÉ

Vector defining the sector. This vector consists of the following elements:

1         X coordinate of the center of the circle
2         Y coordinate of the center of the circle
3         X radius of the circle
4         Y radius of the circle
5         Angle (in degrees) subtended by the sector at the center of the
          circle. Measured counterclockwise from the start position angle.
6         Angle (in degrees) of the start position of the sector, measured
          counterclockwise from the horizontal X axis.

All coordinates are in world coordinate units.

Set on OPEN, then read-only.

Default: ""


ΓòÉΓòÉΓòÉ 166.1.2. TILT ΓòÉΓòÉΓòÉ

Angle at which the sector is tilted. The angle of tilt is specified in degrees
and is measured counterclockwise from the horizontal.

Default: 0 (No tilt)


ΓòÉΓòÉΓòÉ 167. SEND ΓòÉΓòÉΓòÉ

The SEND object class may be used to send data in a chosen format to a
specified location.

Attributes

Actions

Events


ΓòÉΓòÉΓòÉ 167.1. Attributes ΓòÉΓòÉΓòÉ

OBJECTNAME             OWNERWINDOW
VISIBLE                HELP
FORMATS                IDENTIFIER


ΓòÉΓòÉΓòÉ 167.1.1. OBJECTNAME ΓòÉΓòÉΓòÉ

If specified, OBJECTNAME must be a character string of up to 255 bytes. This
string is used to construct the window title of the dialog. If it is not set,
the dialog title is not modified and remains as Send

Set on OPEN, then read-only.

Default: None


ΓòÉΓòÉΓòÉ 167.1.2. OWNERWINDOW ΓòÉΓòÉΓòÉ

If specified, OWNERWINDOW must be a pointer to a window handle. The referenced
window will be made the OwnerWindow of the dialog window. (See WINDOW.)

Set on OPEN, then read-only.

Default: None


ΓòÉΓòÉΓòÉ 167.1.3. VISIBLE ΓòÉΓòÉΓòÉ

Whether the Send dialog is displayed:

0         Dialog not displayed
1         Dialog displayed

Default: 1 (Displayed)


ΓòÉΓòÉΓòÉ 167.1.4. HELP ΓòÉΓòÉΓòÉ

Resource identifier (res ID) of the help text for the Send formats. If
specified, this attribute should be set on OPEN.

Default: None


ΓòÉΓòÉΓòÉ 167.1.5. FORMATS ΓòÉΓòÉΓòÉ

A pointer to a vector of format names, which includes all the formats supported
by the application.

Set on OPEN, then read-only.

Default: None


ΓòÉΓòÉΓòÉ 167.1.6. IDENTIFIER ΓòÉΓòÉΓòÉ

If specified, IDENTIFIER is used to set the initial file name for output files.

Set on OPEN, then read-only.

Default: None


ΓòÉΓòÉΓòÉ 167.2. Actions ΓòÉΓòÉΓòÉ

SEND()


ΓòÉΓòÉΓòÉ 167.2.1. SEND() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSEND(pFormats)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action mails data synchronously. pFormats is a pointer to a scalar or
vector of formats. All the specified formats must be supported by the client.
The client's ON SOURCE block is run once for each format in the vector. Then
the SEND object mails the rendered data.

This action may be used to service an application's Send API. The application
can open the SEND object invisibly and then call the Send action.


ΓòÉΓòÉΓòÉ 167.3. Events ΓòÉΓòÉΓòÉ

QUIT              SOURCE


ΓòÉΓòÉΓòÉ 167.3.1. QUIT ΓòÉΓòÉΓòÉ

Received when the user closes the Send dialog.


ΓòÉΓòÉΓòÉ 167.3.2. SOURCE ΓòÉΓòÉΓòÉ

The client's ON SOURCE block is called and passed a pointer to an SFILE. The
client is expected to populate the SFILE with the relevant data. SFILE'FORMAT
will be set to the required data format.


ΓòÉΓòÉΓòÉ 168. SEPARATE() ΓòÉΓòÉΓòÉ

The SEPARATE() function returns the number of items in a string, or a specified
item in a string.

                            ΓöîΓöÇ" "ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöÇΓöÇSEPARATE(string,number,ΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                            ΓööΓöÇseparatorΓöÇΓöÿ

Examples

More about SEPARATE()

See also: WORDS()


ΓòÉΓòÉΓòÉ 168.1. Examples ΓòÉΓòÉΓòÉ

LET word=SEPARATE("The cat sat on the mat",3)
                                  !  Result is word=sat
LET option=SEPARATE("one;two;three;four;five",3,";")
                                  !  Result is option=three
LET number=SEPARATE("Once upon a time, there were three bears.")
                                  !  Result is number=8
LET number=SEPARATE("Once upon a time,there were three bears.")
                                  !  Result is number=7

Examples source library:


ΓòÉΓòÉΓòÉ 168.2. More about SEPARATE() ΓòÉΓòÉΓòÉ

o SEPARATE() is similar to the WORDS() function. The two functions differ in
  the way they deal with separators.

o If there is only one parameter, or if a number parameter is not supplied,
  SEPARATE() returns the number of separate items in the string. A zero-length
  string produces a result of zero.

o Only SBCS characters can be used as separators. When an SBCS space is used as
  a separator, or separator is omitted, SBCS and DBCS spaces in string are both
  assumed to be separators.

o SEPARATE() (unlike WORDS()) treats nonspace separators differently from space
  separators.  Contiguous spaces are treated as one separator, but each
  occurrence of a nonspace separator delimits a separate item in the string.
  Where two such separators occur contiguously, a zero length item is
  considered to exist.  For example:

    LET x = SEPARATE("a++b++c",3,"+")

  returns:

    x = "b"

o More than one separator character can be supplied. Any of the characters
  supplied can delimit an item. For example:

    LET x = SEPARATE("the cat-?sat+on the/mat",4,"-+/*!?")

  This returns:

    x = "on the"

o If number is negative, it indicates a position relative to the end of the
  string. -1 indicates the last item.

o Spaces and nonspace characters can be combined in the third separator
  parameter. If separator is specified as a space, both SBCS and DBCS spaces in
  the string are assumed to be spaces.


ΓòÉΓòÉΓòÉ 169. SFILE ΓòÉΓòÉΓòÉ

SFILE is based on an OS/2 file. It implements STREAM behavior.

See also: STREAM


ΓòÉΓòÉΓòÉ 170. SHUT ΓòÉΓòÉΓòÉ

The SHUT statement closes an instance of an object.

ΓöÇΓöÇSHUTΓöÇΓöÇinstanceΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Examples

More about SHUT

See also: OPEN


ΓòÉΓòÉΓòÉ 170.1. Examples ΓòÉΓòÉΓòÉ

SHUT main_entry

This closes the window object opened in the example given for the OPEN
statement. (See OPEN.)

Examples source library:


ΓòÉΓòÉΓòÉ 170.2. More about SHUT ΓòÉΓòÉΓòÉ

o Any objects which were opened with instance as parent are also shut when
  instance is shut.

o Any objects which are opened by a program are shut by the system when the
  program terminates.

o For details of what happens when any particular object is shut, see the
  section on that object.

o SHUT can never cause an error, whatever you use it on. If instance is not an
  open object, then SHUT is ignored. This means that you do not need to use
  FORGIVE with SHUT.


ΓòÉΓòÉΓòÉ 171. SIGNAL PROGRAM ΓòÉΓòÉΓòÉ

The SIGNAL PROGRAM statement cancels the suspension of a program caused by a
WAIT PROGRAM statement.

ΓöÇΓöÇSIGNALΓöÇΓöÇPROGRAMΓöÇΓöÇprogramaliasΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Examples

More about SIGNAL PROGRAM

See also: QUEUE PROGRAM, RUN PROGRAM, START, WAIT PROGRAM


ΓòÉΓòÉΓòÉ 171.1. Examples ΓòÉΓòÉΓòÉ

SIGNAL PROGRAM testrun

Examples source library:


ΓòÉΓòÉΓòÉ 171.2. More about SIGNAL PROGRAM ΓòÉΓòÉΓòÉ

o If the named program is waiting for the program which uses SIGNAL, no action
  is taken.

o If another program is waiting for a task which stops, a SIGNAL PROGRAM is
  implied.


ΓòÉΓòÉΓòÉ 172. SIN(), SIND() ΓòÉΓòÉΓòÉ

The SIN() and SIND() functions return the sine of an angle.

SIN() returns the sine value for an angle specified in radians. SIND() returns
the sine value for an angle specified in degrees.

ΓöÇΓöÇSIN(angle)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

ΓöÇΓöÇSIND(angle)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Examples


ΓòÉΓòÉΓòÉ 172.1. Examples ΓòÉΓòÉΓòÉ

x = SIN(0.82)                               !  Result is 0.73
x = SIND(21.1)                              !  Result is 0.36

Examples source library:


ΓòÉΓòÉΓòÉ 173. SLE ΓòÉΓòÉΓòÉ

The SLE object class creates an instance of a single-line edit field.

Parent: WINDOW

Attributes

Actions

Events

Examples

More about SLE


ΓòÉΓòÉΓòÉ 173.1. Attributes ΓòÉΓòÉΓòÉ

AUTOSCROLL            AUTOTAB
BORDER                CLONEDIR
CLONEGAP              CLONES
ENABLED               EXPRESSION
FIRSTCHAR             HANDLES
HELP                  HORZJUST
ORIGIN                PROTECT
SELECTABLE            SIZEX
TEXTLIMIT             VISIBLE
X                     Y


ΓòÉΓòÉΓòÉ 173.1.1. AUTOSCROLL ΓòÉΓòÉΓòÉ

Whether or not the SLE is to have automatic horizontal scrolling:

0         No horizontal scrolling
1         Text scrolls to keep cursor within entry field.

Default: 1 (Scrolling on)


ΓòÉΓòÉΓòÉ 173.1.2. AUTOTAB ΓòÉΓòÉΓòÉ

Whether or not the SLE is to have automatic tabbing:

0         No automatic tabbing
1         Moves the cursor to the next field in the window when the TEXTLIMIT
          size is reached for the SLE.

Default: 0 (No tabbing)


ΓòÉΓòÉΓòÉ 173.1.3. BORDER ΓòÉΓòÉΓòÉ

Framed border half a dialog box unit wide is drawn round entry field:

0         No border
1         Border drawn

Default: 0 (No border)


ΓòÉΓòÉΓòÉ 173.1.4. CLONEDIR ΓòÉΓòÉΓòÉ

Direction of cloning relative to the original:

1         Down
2         Up
3         Left
4         Right

Set on OPEN, then read-only.

Default: 1 (Down)


ΓòÉΓòÉΓòÉ 173.1.5. CLONEGAP ΓòÉΓòÉΓòÉ

Gap between clones, in dialog box units.

Set on OPEN, then read-only.

Default: 0


ΓòÉΓòÉΓòÉ 173.1.6. CLONES ΓòÉΓòÉΓòÉ

Number of clones.

Set on OPEN, then read-only.

Default: 1


ΓòÉΓòÉΓòÉ 173.1.7. ENABLED ΓòÉΓòÉΓòÉ

Whether the SLE field is enabled:

0         SLE displayed, but cannot hold cursor, the user cannot type into it
1         SLE enabled

Default: 1 (Enabled)


ΓòÉΓòÉΓòÉ 173.1.8. EXPRESSION ΓòÉΓòÉΓòÉ

Name of a variable containing data entered by the end user. The contents of the
variable are displayed by the SLE.

Default: ""


ΓòÉΓòÉΓòÉ 173.1.9. FIRSTCHAR ΓòÉΓòÉΓòÉ

Offsets the entry field to the left by a number of characters. The value of
FIRSTCHAR is the number of obscured bytes in the string. For SBCS environments,
this is the same as the number of characters obscured.  However, if there are
any obscured DBCS characters in the string, this relationship does not apply.

An error results if the number specified is greater than the number of
characters.

Default: 0


ΓòÉΓòÉΓòÉ 173.1.10. HANDLES ΓòÉΓòÉΓòÉ

Whether sizing handles are attached to the SLE to support moving, sizing, and
copying operations. These direct manipulation techniques follow the CUA
guidelines. See also the AUTOSELECT attribute of the WINDOW object.

0         Handles are not displayed
1         Handles are displayed

Default: 0 (No handles)


ΓòÉΓòÉΓòÉ 173.1.11. HELP ΓòÉΓòÉΓòÉ

Resource identifier (res ID) of the full help text for this object.

Default: 0


ΓòÉΓòÉΓòÉ 173.1.12. HORZJUST ΓòÉΓòÉΓòÉ

Justification of the text in the entry box:

0         Left justified
1         Right justified
2         Centered

Default: 0 (Left justified)


ΓòÉΓòÉΓòÉ 173.1.13. ORIGIN ΓòÉΓòÉΓòÉ

The corner of the enclosing window to be taken as the origin. The position of
the SLE field is measured from this point.

"TL"      Top left
"TR"      Top right
"BL"      Bottom left
"BR"      Bottom right

Default: "BL" (Bottom left)


ΓòÉΓòÉΓòÉ 173.1.14. PROTECT ΓòÉΓòÉΓòÉ

Whether or not data typed into the SLE is to be displayed:

0         Data displayed.
1         Data not displayed.
Set on OPEN, then read-only.

Default: 0 (Displayed)


ΓòÉΓòÉΓòÉ 173.1.15. SELECTABLE ΓòÉΓòÉΓòÉ

Whether SLE field is selectable:

0         SLE not selectable
1         SLE selectable

Default: 0 (Not selectable)

If ENABLED is set to 0 (not enabled), the value of SELECTABLE is ignored (the
SLE is not selectable).


ΓòÉΓòÉΓòÉ 173.1.16. SIZEX ΓòÉΓòÉΓòÉ

Width of the SLE field, in dialog box units.

Default: 0


ΓòÉΓòÉΓòÉ 173.1.17. TEXTLIMIT ΓòÉΓòÉΓòÉ

Maximum length of text that can be displayed in the SLE box, in bytes (for SBCS
the number of bytes is equal to the number of characters). The maximum
permitted value is 255.

Default: 255


ΓòÉΓòÉΓòÉ 173.1.18. VISIBLE ΓòÉΓòÉΓòÉ

Whether the SLE field is displayed:

0         SLE not displayed
1         SLE displayed

Default: 1 (Displayed)


ΓòÉΓòÉΓòÉ 173.1.19. X ΓòÉΓòÉΓòÉ

Horizontal position of the bottom left-hand corner of the SLE field, in dialog
box units.

Default: 0


ΓòÉΓòÉΓòÉ 173.1.20. Y ΓòÉΓòÉΓòÉ

Vertical position of the bottom left-hand corner of the SLE field, in dialog
box units.

Default: 0


ΓòÉΓòÉΓòÉ 173.2. Actions ΓòÉΓòÉΓòÉ

EDIT()               REFRESH()
SELAREA()


ΓòÉΓòÉΓòÉ 173.2.1. EDIT() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇEDIT(argument)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Enables the programmer to query whether a clipboard operation is supported and,
if it is, to carry it out.

argument is a clipboard query or a clipboard operation.

The following values for argument are used to check whether particular
clipboard operations can be supported with the SLE field in its current state:

"Querycut" Cut to clipboard
"Querycopy" Copy to clipboard
"Querypaste" Paste from clipboard
"Queryclear" Clear clipboard.

Where clipboard operations are supported, the following values for argument
direct them to be carried out:

"Cut"     Cut to clipboard
"Copy"    Copy to clipboard
"Paste"   Paste from clipboard
"Clear"   Clear clipboard.


ΓòÉΓòÉΓòÉ 173.2.2. REFRESH() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇREFRESH()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Forces repainting of the SLE field on screen.


ΓòÉΓòÉΓòÉ 173.2.3. SELAREA() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSELAREA(start,length)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action selects all or part of the text string in the SLE part of the SLE
control. The default value for start is 1, and it must be in the range 1
through 255. The default value for length is 0, and it must be in the range 0
through 255. start plus length must be less than or equal to 256.

The current insertion point is placed after the last selected character. If
length is 0, the insertion point is placed before the character position
specified in start.


ΓòÉΓòÉΓòÉ 173.3. Events ΓòÉΓòÉΓòÉ

DATA               DESKTOP
SELECT


ΓòÉΓòÉΓòÉ 173.3.1. DATA ΓòÉΓòÉΓòÉ

Signaled if data has changed within the SLE when another object is selected or
the TAB key is pressed. A.System.Object is set to named control and
A.System.Boxnumber is set to the clone selected.


ΓòÉΓòÉΓòÉ 173.3.2. DESKTOP ΓòÉΓòÉΓòÉ

Signaled when the SLE is moved, sized, or copied. A.System.Operation is set to
"MOVE", "SIZE", or "COPY". A.System.Object contains the name of the control.


ΓòÉΓòÉΓòÉ 173.3.3. SELECT ΓòÉΓòÉΓòÉ

Signaled when selection is made. Only available if the SELECTABLE attribute is
set (SELECTABLE=1). A.System.Object is set to named control and
A.System.Boxnumber is set to the clone selected.


ΓòÉΓòÉΓòÉ 173.4. Examples ΓòÉΓòÉΓòÉ

! Open samples of the SLE control.
! Two samples are opened, one the simplest form of SLE, the
! second is cloned and has a solid border.
PROCEDURE SLE
DO
  !
  ! a simple sle
  !
  LET sledata="Sample text"
  OPEN SLE sle1, Win,
   SizeX =  60,                  ! sizey is not applicable to an SLE
   X     =  10, Y =  85,
   Expression = "sledata",
   Border     = 0                ! no border (default)
  !
  ! open a cloned sle, referenced to the 'days' array
  !
  OPEN SLE sle2, Win,
   SizeX       = 80,
   X = 5,    Y = 70,
   Expression  = "days[1]",
   Clones      = 5,               ! number of clones
   CloneGap    = 3,               ! gap between clones
   CloneDir    = 1,               ! clone direction - vertically down
   Border      = 1                ! solid border
END

Examples source library:


ΓòÉΓòÉΓòÉ 173.5. More about SLE ΓòÉΓòÉΓòÉ

o The following attributes can only be modified for the entire clone set, not
  for the individual clones:

   CLONEDIR
   CLONEGAP
   ORIGIN
   HANDLES
   SELECTABLE
   VISIBLE

If you wish to modify an attribute for the entire clone set use a reference of
zero:

LET mypush[0]'VISIBLE=0
The set reference of zero must be used even when the SLE does not have any
clones.

o In a DBCS environment, a window containing an SLE has a keyboard status line
  at the bottom for character conversion. This line is added automatically.


ΓòÉΓòÉΓòÉ 174. SMEMORY ΓòÉΓòÉΓòÉ

SMEMORY implements STREAM behavior, based on a contiguous area of memory.

See also: STREAM


ΓòÉΓòÉΓòÉ 175. SOUND ΓòÉΓòÉΓòÉ

The SOUND statement produces a sound of a specified frequency and duration.

                         ΓöîΓöÇ1ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöÇΓöÇSOUNDΓöÇΓöÇfrequencyΓöÇΓöÇ,ΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                         ΓööΓöÇdurationΓöÇΓöÿ

Examples

See also: MMFILE


ΓòÉΓòÉΓòÉ 175.1. Examples ΓòÉΓòÉΓòÉ

SOUND 1,3        !  Produces a note of 220Hz for 0.3 seconds.
SOUND 600,2      !  Produces a note of 600Hz for 0.2 seconds.
SOUND 30,10      !  Produces a pause for 1 second.

Examples source library:


ΓòÉΓòÉΓòÉ 176. SOURCECTRL ΓòÉΓòÉΓòÉ

This object allows the direct manipulation capabilities of an application (as a
source of data) to be defined. It may be associated with a window to enable
that window to be dragged.

Attributes

Actions

Events

Examples

See also: DDECLIENT, DDESERVER, STREAM, TARGETCTRL, REFERENCE


ΓòÉΓòÉΓòÉ 176.1. Attributes ΓòÉΓòÉΓòÉ

CODE                   DISCARDABLE
OPERATION              OPERATIONS
OBJECTNAME             ORIGINATOR
TRACE                  PRINTABLE


ΓòÉΓòÉΓòÉ 176.1.1. CODE ΓòÉΓòÉΓòÉ

The error code of the last SOURCECTRL operation.

Default: None

Read-only


ΓòÉΓòÉΓòÉ 176.1.2. DISCARDABLE ΓòÉΓòÉΓòÉ

Indicates whether or not the represented object can be discarded, by, for
example, being dragged to a shredder, or otherwise being removed from its
current location.

When DISCARDABLE is set to 1 (true), then each associated screen object can be
dropped on a shredder icon. This generates a DISCARD event.

Default: 1 (True) Set on OPEN, then read/write.


ΓòÉΓòÉΓòÉ 176.1.3. OPERATION ΓòÉΓòÉΓòÉ

Identifies the drag/drop operation: M, C, or L.


ΓòÉΓòÉΓòÉ 176.1.4. OPERATIONS ΓòÉΓòÉΓòÉ

Indicates the operations supported by the source.

It should be a character string including one instance of one or more of the
following characters:

M         Move
C         Copy
L         Link

If any character other than those above is specified, an error condition will
result.

The implications of allowing a Move are that the ASL program may receive an ON
DISCARD event. If discarding the represented would cause problems (for instance
if the object was an essential part of the implementation of another containing
object) then Move should not be allowed. Support for Move implies that
DISCARDABLE = 1, and overrides the setting of DISCARDABLE. The OPERATION
attribute on SOURCECTRL or TARGETCTRL will be set to M, C or L to identify the
operation.

Default: C Set on OPEN, then read/write


ΓòÉΓòÉΓòÉ 176.1.5. OBJECTNAME ΓòÉΓòÉΓòÉ

This attribute provides qualifying information to a target when a drop occurs.
(The value is used to set the targetname value for the OS/2 protocol.)

When a drop occurs the OBJECTNAME attribute of the STREAM will match the
OBJECTNAME attribute of SOURCECTRL. OBJECTNAME may be set to any character
string up to 255 bytes in length.

Default: None Set at OPEN, then read/write


ΓòÉΓòÉΓòÉ 176.1.6. ORIGINATOR ΓòÉΓòÉΓòÉ

Identifies the screen object that was dragged. The attribute will be set to
point to the handle of the dragged object.

Default: None

Read-only


ΓòÉΓòÉΓòÉ 176.1.7. TRACE ΓòÉΓòÉΓòÉ

This Boolean attribute controls whether trace information will be recorded. The
trace information includes the following items:

o The object class (SOURCECTRL or TARGETCTRL).

o The object class of the associated screen object.

o The object token for the screen object.

o The ASL event name.

o The current CODE attribute value.

o Each action invoked, along with parameter values (truncated to 20 bytes per
  parameter, and only the first element of any vector parameter).

o Lower level Drag API function calls and control block data.
The trace data is limited to records of 64 characters or less.

Drag/Drop trace will be written to a file called FTBDRG in the FTB1DIR
directory.

Default: 0 (No tracing) Set on OPEN, then read-only.


ΓòÉΓòÉΓòÉ 176.1.8. PRINTABLE ΓòÉΓòÉΓòÉ

Indicates whether or not the represented object is capable of producing print
output.

When PRINTABLE is set to 1 (true), then the window can be dropped on any
printer icon. This generates a PRINT event.

Default: 0 (False) Set on OPEN, then read/write.


ΓòÉΓòÉΓòÉ 176.2. Actions ΓòÉΓòÉΓòÉ

ADDFORMAT()            ADDTYPE()
FORMATS()              SETIMAGE()
TYPES()


ΓòÉΓòÉΓòÉ 176.2.1. ADDFORMAT() ΓòÉΓòÉΓòÉ

                      ΓöîΓöÇ0ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöÇΓöÇADDFORMAT(format,ΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                      ΓööΓöÇreferenceΓöÇΓöÿ

This action may be used to signify that a source data format is supported.

format is a character string representing a data format name, such as DIF, IXF,
DBF, IBMCHART.

reference is a Boolean parameter that indicates when 1 (true) that a reference
to data in the associated format can be provided. The reference could be
achieved by saving data into a file and supplying a reference to that file on
request.

When a reference to data is requested by a target, the REFERENCE attribute of
the STREAM object delivered with the SOURCE event will be 1 (true) and the
FORMAT attribute will specify the required format. The REFERENCE object should
be used to supply reference information.

Repeated ADDFORMAT requests are cumulative, and may be used to build up a set
of supported target formats and operations.


ΓòÉΓòÉΓòÉ 176.2.2. ADDTYPE() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇADDTYPE(Type)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action may be used to signify that the object represents a source type.

Type is provided by the caller, and should be a character string representing a
type name.

Repeated ADDTYPE requests are cumulative, and may be used to build up a set of
supported source types.


ΓòÉΓòÉΓòÉ 176.2.3. FORMATS() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇFORMATS(formats,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                     ΓööΓöÇreferenceΓöÇΓöÿ

This action may be used to define a complete set of supported source formats.

formats is the name of a scalar or vector containing data format names. Each
value must conform to the same rules as for the format attribute of the
ADDFORMAT action.

reference is the name of a scalar or vector containing values that conform to
the rules for the reference parameter on the ADDFORMAT action.

The FORMATS action replaces any prior definition of supported source formats.


ΓòÉΓòÉΓòÉ 176.2.4. SETIMAGE() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSETIMAGE(type,location)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action may be used to identify the bitmap or icon to be used to represent
the object while it is being dragged.

type is mandatory and specifies the location type of the bitmap or icon. It
must have a value of

FILE      if the bitmap or icon is in a file
DLL       if the bitmap or icon is in a DLL.

location is mandatory and specifies the location of the bitmap or icon. If type
is "FILE", it should be a fully qualified file identifier specifying the drive
and directory, or using the UNC (Universal naming Convention). The file
extension must be  .ICO if the image is an icon, and  .BMP if the image is a
bitmap. The length of the identifier is limited to 255 bytes. If type is "DLL",
it should be of the form  DLLName(ID), where DLLName is the name of the dynamic
link library containing bitmap or icon, and ID is the resource id within the
DLL.


ΓòÉΓòÉΓòÉ 176.2.5. TYPES() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇTYPES(types)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action may be used to specify the TYPEs of the source.

Types is the name of a scalar or vector, declared or undeclared, containing
type name(s).

The TYPES action will replace any prior definition of types.


ΓòÉΓòÉΓòÉ 176.3. Events ΓòÉΓòÉΓòÉ

SOURCE(pStream)            PRINT(pPrinter)
DISCARD(pSrctrl)           ERROR


ΓòÉΓòÉΓòÉ 176.3.1. SOURCE(pStream) ΓòÉΓòÉΓòÉ

This event is triggered when a valid drop occurs. pStream is a pointer to a
STREAM object delivered with the event, through which the data may be rendered.
The ORIGIN attribute of the STREAM object passed with the SOURCE event
identifies the SOURCECTRL object through which the event was generated. The
ORIGIN attribute of the SOURCECTRL object identifies the target screen object.

You can use the FORMAT attribute of the STREAM object to identify the data
format required. If a reference to the data is required, then the REFERENCE
attribute of the STREAM will be 1 (true). A REFERENCE object should be used to
to supply this information.

At the end of ON SOURCE processing, the FINISHED() action of the STREAM should
be called.


ΓòÉΓòÉΓòÉ 176.3.2. PRINT(pPrinter) ΓòÉΓòÉΓòÉ

This event is triggered when an associated screen object is dropped onto a
printer. pPrinter is a pointer to a PRINTER object delivered with the event,
through which the represented object may print. The ORIGIN attribute of the
PRINTER object passed with the SOURCE event identifies the SOURCECTRL object
through which the event was generated. The ORIGIN attribute of the SOURCECTRL
object identifies the screen object that was dragged.

At the end of ON PRINT processing, the PRINTER object should be SHUT.


ΓòÉΓòÉΓòÉ 176.3.3. DISCARD(pSrctrl) ΓòÉΓòÉΓòÉ

This event is triggered after data has been successfully delivered by a SOURCE
event, where the operation was a Move, or after the object has been dropped on
the shredder.

pSrctrl is a pointer to the SOURCECTRL object that was associated with the
window that was dragged. The ORIGINATOR attribute of the SOURCECTRL object may
be used to identify the window that was dragged. This window, and the objects
it represented should be discarded.


ΓòÉΓòÉΓòÉ 176.3.4. ERROR ΓòÉΓòÉΓòÉ

An error has occurred during processing the drop.


ΓòÉΓòÉΓòÉ 176.4. Examples ΓòÉΓòÉΓòÉ

See DRAGDROP.PRG (part of the DATAEXCH example) in Development Samples for more
information.

Examples source library:


ΓòÉΓòÉΓòÉ 177. SPACE() ΓòÉΓòÉΓòÉ

The SPACE() function returns a format value which specifies that some spaces
are required in the output file when this value is written to an output device
(such as a printer) which supports lines of output.

ΓöÇΓöÇSPACE(ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
           ΓööΓöÇexpressionΓöÇΓöÿ

Examples

More about SPACE()

See also: LINE(), PAGE(), PRINTER


ΓòÉΓòÉΓòÉ 177.1. Examples ΓòÉΓòÉΓòÉ

CALL Printer'PUT("Pages:",Page_number,Space(10),"Name",Empname)

String=SPACE(15)

Examples source library:


ΓòÉΓòÉΓòÉ 177.2. More about SPACE() ΓòÉΓòÉΓòÉ

o If the COUNT attribute is zero, then no spaces are provided on the output
  file.  This can be useful when the spacing is not known at the time of
  writing the program.

o A format value of SPACE() on a PUT() function is equivalent to a literal or
  variable composed of the same number of spaces.


ΓòÉΓòÉΓòÉ 178. SPLIT() ΓòÉΓòÉΓòÉ

The SPLIT() function extracts part of the value of an expression.

ΓöÇΓöÇSPLIT(expression,start,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ,ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                            ΓööΓöÇlengthΓöÇΓöÿ    Γöé            ΓöîΓöÇ"L"ΓöÇΓöÇΓöÇΓöÉ Γöé
                                          Γö£ΓöÇΓöÇΓöÇfillΓöÇΓöÇ,ΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöñ
                                          Γöé            ΓööΓöÇalignΓöÇΓöÿ Γöé
                                          Γöé ΓöîΓöÇ" "ΓöÇΓöÇΓöÉ             Γöé
                                          ΓööΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇ,ΓöÇΓöÇalignΓöÇΓöÇΓöÇΓöÿ
                                            ΓööΓöÇfillΓöÇΓöÿ

Examples

More about SPLIT()

See also: CSPLIT()


ΓòÉΓòÉΓòÉ 178.1. Examples ΓòÉΓòÉΓòÉ

String = "the cat sat on the mat"
x = SPLIT(String,16)                  !  Result is "the mat"
x = SPLIT(String,5,3)                 !  Result is "cat"
x = SPLIT(String,20,8,".")            !  Result is "mat....."
x = SPLIT(String,20,8,".","R")        !  Result is ".....mat"

Examples source library:


ΓòÉΓòÉΓòÉ 178.2. More about SPLIT() ΓòÉΓòÉΓòÉ

o start and length refer to the number of bytes rather than the number of
  characters.  In SBCS environments, the number of characters equals the number
  of bytes.

  In the following example, suppose that c is a DBCS character:

    x = SPLIT("the cat sat on the mat",9)

  Here,  SPLIT() returns " sat on the mat".

  Similarly,

    x = SPLIT("the cat sat on the mat",5,7)

  if t and a are DBCS characters, then  SPLIT(x) returns " cat ", rather than
  "cat sat", as it would if all the characters were SBCS.

o The value produced by SPLIT() is assigned the appropriate data type.  Values
  longer than the maximum system string length are reduced to that length.

o No error is caused if positive, but not valid, values are given for start and
  length. The appropriate defaults are assumed instead (a default of 1 is
  assumed for start). Negative values cause an error.

o SPLIT() behaves differently in a DBCS environment.

  If start is at a DBCS second byte, SPLIT() extracts the substring from the
  first byte of the pair.

  length is always calculated from the start point specified by the end user,
  even if this is the second byte of a DBCS pair. If the last position to be
  extracted is at a DCBS first byte, the last position is changed to the
  character preceding the DBCS character.

o Only SBCS characters can be used as fill characters.  DBCS characters cannot
  be used.


ΓòÉΓòÉΓòÉ 179. SQLSESSION ΓòÉΓòÉΓòÉ

The SQL interface provides SQL data access.

Attributes

Actions

Events: None.

More about SQLSESSION

See also: SQLTRANS


ΓòÉΓòÉΓòÉ 179.1. Attributes ΓòÉΓòÉΓòÉ

CODE                  CODEDETAIL
DBNAME                DRIVE
PLATFORM              SQLSTATE
STATUS                USERID
TRACELEVEL


ΓòÉΓòÉΓòÉ 179.1.1. CODE ΓòÉΓòÉΓòÉ

The latest return code from any action or change of state.

Read-only.

Default: 0 (If successful)


ΓòÉΓòÉΓòÉ 179.1.2. CODEDETAIL ΓòÉΓòÉΓòÉ

In most cases where this value is nonzero it will hold an SQL code (refer to
OS/2 ES 1.0 Messages and Error Recovery Guide or DB2/2 Messages and Problem
Determination Guide See also More about SQLSESSION.


ΓòÉΓòÉΓòÉ 179.1.3. DBNAME ΓòÉΓòÉΓòÉ

The name of the SQL database being accessed.  There is no default for the
database name. If it is not set or is set to nulls, then no database access is
current.  DBNAME can be modified.  There are some situations where you might
want to create an SQLSESSION object without knowing the name of the database
that you will eventually access.

DBNAME takes the value of an alias of a database to ensure that the name is
unique within the system. This makes it possible to access two databases with
the same name, but located on different drives or systems.

Note:   If DBNAME is modified while a cursor is open, the SQLSESSION object
        calls the GOTOTOP action in respect of any child SQLTRANS object with
        an open cursor.  This closes any open queries and resets any open
        cursor.

The following code sets the database name to SAMPLE and retrieves a list of
tables:

Session'DBNAME = "SAMPLE"  ! Attach to the SAMPLE database
CALL Session'TABLENAMES(Tables)
! Retrieve a list of tables in the sample database

Default: No default name


ΓòÉΓòÉΓòÉ 179.1.4. DRIVE ΓòÉΓòÉΓòÉ

The drive to access.  This is used when getting the names of databases. You can
set it to zero to access the system directory of databases. DRIVE can be
modified.

Default: Current drive name


ΓòÉΓòÉΓòÉ 179.1.5. PLATFORM ΓòÉΓòÉΓòÉ

The database platform in use.

This attribute will only be valid when the object has been successfully
attached to a database, (the DBNAME attribute has been set correctly). The
attribute is read-only and can contain the following values:

Blank     When the object is not attached to any database

ES DBM    The currently attached database name is an alias of an ES DBM
          database

DB2       The currently attached database name is an alias of a DB2 subsystem

DB2/2     The currently attached database name is an alias of a DB2/2 subsystem

OS/6000   The currently attached database name is an alias of a DB2/6000
          subsystem

SQL/DS    The currently attached database name is an alias of a SQL/DS
          subsystem

OS400     The currently attached database name is an alias of an OS/400
          collection

UNKNOWN   The currently attached database name is an alias of an unknown
          database platform.

The SQL object has the ability to read data from and write data to DB2, SQL/DS,
OS/400, and SQL/400 tables without the need for Host AS.


ΓòÉΓòÉΓòÉ 179.1.6. SQLSTATE ΓòÉΓòÉΓòÉ

The values are the SQLSTATE standard error codes as returned in the SQLCA by an
SQL operation against a database.

The codes are five character strings and are defined in the IBM Extended
Services/2 Version 1.0 Messages and Error Recovery Guide and DB2/2 Messages and
Problem Determination Guide The attribute is read-only and is valid only after
an SQL operation on a database.


ΓòÉΓòÉΓòÉ 179.1.7. STATUS ΓòÉΓòÉΓòÉ

The status of the database connection:

"N"       No connection
"X"       Exclusive use of the attached database
"S"       Shared access of the attached database.

Default: "S" if DBNAME was specified when opening the session.

The attribute may be changed to "X" or "S" (but not to "N") to change the level
of the connection.  If the SQLSESSION object is not currently attached to a
database (that is the DBNAME is not set to a valid name), attempting to modify
STATUS will have no effect and its value will remain "N".


ΓòÉΓòÉΓòÉ 179.1.8. USERID ΓòÉΓòÉΓòÉ

A text string of eight characters containing the DBM user ID.  If not set, it
defaults to the system defined user ID (that is the currently logged on user).
USERID can be modified to allow you to list and use tables created or owned by
a different user ID. Some actions, such as attempting to attach to a database,
will result in an automatic logon sequence.

Default: User id of logged-on user


ΓòÉΓòÉΓòÉ 179.1.9. TRACELEVEL ΓòÉΓòÉΓòÉ

Initiates a trace and generates or appends the information to the log file,
FTBSQL.

0         Trace off
1         Trace on

Specified on OPEN, the read-only.

Default: 0 (Off)


ΓòÉΓòÉΓòÉ 179.2. Actions ΓòÉΓòÉΓòÉ

COMMAND()               COMMIT()
DBNAMES()               ROLLBACK()
TABLENAMES()


ΓòÉΓòÉΓòÉ 179.2.1. COMMAND() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇCOMMAND(string,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                    ΓööΓöÇvectorΓöÇΓöÿ

Takes a single parameter which can be any character string value, such as a
constant, a data item, or an expression.  It can also be a vector, in which
case all elements of the vector are appended to make the string or command
string. The limit of the length of the string is dependent on the database
product being accessed, but this is not likely to be exceeded in practice.

The string is passed to SQL for immediate execution without any processing,
interpretation, or modification by Visualizer. Only one command can be
processed on each occasion that the action is called.

COMMAND uses the EXECUTE IMMEDIATE statement.  (Refer to the DBM reference
manuals for information on the difference between EXECUTE and EXECUTE
IMMEDIATE, not all SQL commands are available in the IMMEDIATE form.)

If the optional vector is specified, any message resulting from the command is
returned in it.

An example of COMMAND is shown below:

DEFINE Command[0]
INSERT Command[0] = "CREATE TABLE SQLTEST "
INSERT Command[0] = "(COLUMN1  CHAR(20),"
INSERT Command[0] = " COLUMN2  SMALLINT NOT NULL)"
CALL Session'COMMAND(Command[0])
    ! Pass the immediate SQL command in the vector
    ! Command to SQL.  This will create a new table
    ! in the SAMPLE database
CALL Session'ROLLBACK
    ! Decommit the previous changes to the database.
    ! The table just created will no longer exist


ΓòÉΓòÉΓòÉ 179.2.2. COMMIT() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇCOMMIT()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

The commit finishes a logical piece of work by setting it into the database.
If a problem occurs in the database then any work since the last commit would
be rolled back to ensure database integrity. Therefore you must perform a
COMMIT to save changes to a database.

Since the commit operation closes all queries, it results in the loss of all
prepares and cursors for a process. This loss of resources has a number of
implications, a query defined against some table may become locked out from the
table by another process.  This other process could change the structure of the
table or even delete the table.  The most likely effect though would be
changing the data in the table.

It is possible to run the same query (snapshot) twice with a commit or rollback
between and have entirely different results (different values for the results
or even a failure to produce any results). Therefore it is advisable to use
caution when producing ASL application code since there can be many tasks
running cooperatively in Visualizer. If more that one task could be accessing
the database, then ensure that each action completes all work prior to
relinquishing control or that the tasks synchronize any changes.

Problems with side effects of commits should not be a problem between separate
Visualizer processes, but only within a single Visualizer process. It is
advisable to use COMMIT after a query is complete to release the read locks.

Committing work is recommended - just be aware of the change in the state of
the tables that results from the commit.  Two problems arise when work is not
committed on a regular basis:

o Large numbers of changes may be lost due to a rollback.

o Another process may be waiting to use a table or record that is already
  locked. The process which holds that lock has the responsibility for
  releasing it (by either committing or rolling back the work it has done) as
  soon as possible.

There are no parameters to this action.


ΓòÉΓòÉΓòÉ 179.2.3. DBNAMES() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇDBNAMES(alias,ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇ,ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇ,ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇ,ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                    ΓööΓöÇdbnameΓöÇΓöÿ     ΓööΓöÇdbtypeΓöÇΓöÿ     ΓööΓöÇcommentΓöÇΓöÿ
ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇ,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
   ΓööΓöÇdriveΓöÇΓöÿ    ΓööΓöÇnodeΓöÇΓöÿ

Provides information, in the form of parallel vectors, on the databases
available. The information provided depends on the parameters given with the
action. alias is mandatory, all other parameters are optional. The parameters
are defined as follows:

alias     List of database aliases.  An alias is an alternate database name. A
          database on one system may have the same name as that on one on
          another system.  The alias is used to uniquely identify all available
          databases. This name is required for attachment to the database.

dbname    List of database names.

dbtype    Database types:

   0         Local
   1         Remote
   2         No user ID currently logged on (type is not known)

comment   Database comments.

drive     The drive upon which the database resides.

node      The node the database resides on (DDCS/2 for example)


ΓòÉΓòÉΓòÉ 179.2.4. ROLLBACK() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇROLLBACK()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

The rollback action finishes a Logical Unit of Work (LUW) by reverting the
state of the database to that it was in immediately after the last LUW or start
of access, thereby cancelling a unit of work.

The rollback will release all resources held by the DBM for this process. This
may cause a problem if, for example, an expression has been set into a SQLTRANS
object and this LUW ending allows tables specified in the expression to be
dropped.  If the SQLTRANS object were to then execute a SNAPSHOT, an error
would occur.

Detach from a database will cause a rollback.  Therefore if changes performed
before ending a session with the DBM are to be saved, you must perform a
COMMIT.

There are no parameters to this call.


ΓòÉΓòÉΓòÉ 179.2.5. TABLENAMES() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇTABLENAMES(table,type,cols,rows)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Once a database access is current, you can request a list of tables and views
in the SQL database.  These are returned as parallel vectors, all except table
are optional. The table details are those of the tables created with the
qualifier name specified in the USERID attribute for an OS/2 DBM database:

table     List of table names (mandatory).

type      List of table types.  In this context a table can be either a base
          table ("T"), or a view ("V").

cols      Number of columns in the table or view.

rows      If statistics are being maintained, the number of rows in each table
          or view.  If statistics are not being maintained, then this is
          denoted by -1.

Each platform holds information on indices, tables, and views differently.  The
product creates views against this information for its own purposes.  For more
information, see the installation instructions for the database.


ΓòÉΓòÉΓòÉ 179.3. More about SQLSESSION ΓòÉΓòÉΓòÉ

o The SQL interface extends the data access capabilities of Visualizer to
  include Database2/2 and OS/2 Extended Services Database Manager databases,
  and also the following SQL databases, accessible through either of these
  products, if OS/2 Distributed Database Connection Service (DDCS/2) is also
  installed:

   - DB2
   - SQL/DS*
   - OS/400 and SQL/400

  You can develop Visualizer applications that can use any valid SQL statement
  to query a database running under DB2/2 or DBM, or accessed through either
  product, and place the result into Visualizer tables. Applications can place
  data into a SQL base table and deliver the table objects to the database
  product. Applications can also use a Visualizer table as a template for the
  creation of SQL tables. (See IBM Visualizer for OS/2: Installing and
  Supporting

  The SQL table objects provide the following benefits:

   - Conformity to SAA guidelines
   - Security and integrity facilities
   - Ability to join and aggregate data in an efficient manner
   - Ability to share data with others.

  It is possible to access DB2/2 or OS/2 DBM and through either, to access data
  held on any other database connected remotely to them. In order to do this,
  you must have the following:

   - A suitable connection to an OS/2 DBM or DB2/2 server (Refer to IBM OS/2 ES
     Guide to Database Manager Clients IBM DB2/2 Information and Planning Guide

   - The Visualizer-OS/2 DBM or Visualizer-DB2/2 installation procedure must
     have been performed for each database that needs to be accessed, including
     the OS/2 DBM and DB2/2 databases. (See IBM Visualizer for OS/2: Installing
     and Supporting

   - To access databases available using DDCS/2, the required DDCS/2
     definitions must have been performed.

  With the SQLSESSION object you can:

   - Inquire about the availability of databases, and their status

   - Access a particular database

   - Inquire about what tables or views exist within a database

   - Control SQL Logical Units of Work (LUW)

   - Use commands executable by the EXECUTE IMMEDIATE statement (that is,
     commands that do not require preparation).

     EXECUTE can be used for commands at the table level as well as at the
     database level. (For details of commands, refer to the appropriate command
     reference information for the database product being accessed.)

  In order to retrieve data you must use a combination of the SQLSESSION object
  (to open the database and, if necessary, inquire on tables or views), and the
  SQLTRANS object or objects (to specify the selection requests and obtain the
  data).

  Data can be obtained one row at a time or in multiple rows by retrieving
  whole, or large parts, of an SQL query result. Modification of data within
  SQL tables can be done in one of two ways:

   - By reading data from the result of an SQL query into a local table,
     modifying the data in the local table, then loading the local table to SQL
     to overwrite the previous table.

   - By using the Command action to send an SQL statement to the remote SQL
     database.

  You may only have one SQLSESSION object open at any one time in a Visualizer
  application since OS/2 DBM allows only one database open per process at any
  one time.  Therefore concurrent access to multiple databases is not
  supported.

  The SQLSESSION object is the parent of all SQLTRANS object instances. If the
  SQLSESSION object is closed, the many SQLTRANS objects which are dependent on
  the SQLSESSION will also be closed.  Since there can be multiple SQLTRANS
  objects, you can access multiple tables at the same time.

  The database accessed can be any database accessible through OS/2 DBM or
  DB2/2.

  The code below opens a session and identifies the databases available:

    OPEN SQLSESSION Session,
                DRIVE = "0"          ! Use the SQL system catalog
    CALL Session'DBNAMES(DataBases)  ! Retrieve a list of databases
                                     ! (will create the vector)

o Only one SQLSESSION object can exist at any one time.

o In most cases, when the CODEDETAIL attribute is nonzero, it contains the
  SQLCODE value passed from OS/2 Database Manager. The following table
  describes the only exceptions, where values for CODEDETAIL are associated
  with Visualizer FTB messages, and gives the meaning of the CODEDETAIL
  attribute value in that context.

   Message   Meaning of CODEDETAIL Attribute

   FTB8500   System call... was unsuccessful.

             During the execution of SQL interface code, a call to a system
             routine failed. The CODEDETAIL attribute provides the
             Dosreturncode return code from the system call.

             Note:   Message FTB8500 is accompanied by message FTB8504 which
             displays the OS/2 system error code.  To display the meaning of
             these codes type the OS/2 command HELP in an OS/2 window, followed
             by a space, then the number of the error.

   FTB8528   The database product was not successfully started.

             There has been a failure in a database product utility. The return
             code from STARTDBM (or equivalent) is shown by the value in
             CODEDETAIL.

   FTB8536   The SQL interface could not place data into a variable or vector.

             The value in CODEDETAIL, if nonzero, indicates the number of a
             column containing a value that has failed to convert into a
             Visualizer date or time value. This is due to a failure of the
             SNAPSHOT action.

   FTB8560   Strings returned by the SQL query exceeded the string length and
             have been truncated.

             The value in CODEDETAIL is the original length of the truncated
             string.

   FTB8649   One or more values in a column of a Visualizer table could not be
             converted to a SQL value. The missing column information in the
             SQL table has been replaced by nulls.

             The value in CODEDETAIL is the number of the column containing the
             value or values that failed to convert.


ΓòÉΓòÉΓòÉ 180. SQLTRANS ΓòÉΓòÉΓòÉ

The SQLTRANS object allows you to access and store data in an SQL table.

Parent: SQLSESSION

Attributes

Actions

Events: None.

More about SQLTRANS

See also: SQLSESSION


ΓòÉΓòÉΓòÉ 180.1. Attributes ΓòÉΓòÉΓòÉ

CODE                  CODEDETAIL
EOF                   GENKEYCOL
MODE                  TABLE
SQLSTATE


ΓòÉΓòÉΓòÉ 180.1.1. CODE ΓòÉΓòÉΓòÉ

The latest return code from any action or change of state. This is a read-only
attribute.

Default: 0 (If successful)

CODE can contain error numbers describing OS/2, DBM (or DB2/2), or interface
errors.


ΓòÉΓòÉΓòÉ 180.1.2. CODEDETAIL ΓòÉΓòÉΓòÉ

In most cases where this value is nonzero it will hold an SQL code (refer to
OS/2 ES 1.0 Messages and Error Recovery Guide or DB2/2 Messages and Problem
Determination Guide See also More about SQLSESSION.

Default: 0 (If successful)


ΓòÉΓòÉΓòÉ 180.1.3. EOF ΓòÉΓòÉΓòÉ

EOF is set to 1 (true) when all rows from a query have been returned by a
SNAPSHOT or GETNEXTROW action.

Read-only.


ΓòÉΓòÉΓòÉ 180.1.4. GENKEYCOL ΓòÉΓòÉΓòÉ

A name to be used by a column to hold a generated key sequence. If set, an
extra column will be added to the Visualizer table generated by a SNAPSHOT or
GETNEXTROW action. This will override any SETKEYS setting and be the key for
the table.

Default: None

Oldkeys = Trans1'GenKeyCol
! set Oldkeys to the current key sequence
Trans1'GenKeyCol = Newkeys
! set the key sequence to NewKeys

Note:   You cannot modify GENKEYCOL when the cursor is open as the destination
        table for the SNAPSHOT or GETNEXTROW operation has already been
        prepared.


ΓòÉΓòÉΓòÉ 180.1.5. MODE ΓòÉΓòÉΓòÉ

The direction of data transfer for this instance of the object. Can be set on
OPEN, then read-only.

"R"       Read
"L"       Load

Default: Read

If both reading and writing to the same database is required, two SQLTRANS
objects are required as shown below:

  OPEN SQLTRANS Trans1,
                Session,
                TABLE = Tab,
                MODE = "R"
  OPEN SQLTRANS Trans2,
                Session,
                TABLE = Tab,
                MODE = "L"

The mode can be examined by using the LET statement:

LET Read_Or_Load = Trans2'MODE


ΓòÉΓòÉΓòÉ 180.1.6. TABLE ΓòÉΓòÉΓòÉ

The handle of the Visualizer table object to be used. For READ, this must
identify an empty table with no columns defined. For LOAD, actions use the
definition of the table and its contents.

Default: None

CurrentTable = Trans1'TABLE
! set CurrentTable to be a POINTER to the Table object
OPEN TABLE NewTable,
 NAME     = Name(NewFileName),
 LOCATION = Location(NewFileName),
 MODE     = "WRITE"

Trans1'TABLE = NewTable
! Set the Table attribute to NewTable

Note:   You cannot modify TABLE during a SNAPSHOT operation, or in other
        circumstances when the cursor is open.


ΓòÉΓòÉΓòÉ 180.1.7. SQLSTATE ΓòÉΓòÉΓòÉ

The values are the SQLSTATE standard error codes as returned in the SQLCA by an
SQL operation against a database.

The codes are five character strings and are defined in the document OS/2 ES
1.0 Messages and Error Recovery Guide and DB2/2 Messages and Problem
Determination Guide The attribute is read-only and is valid only after an SQL
operation on a database.


ΓòÉΓòÉΓòÉ 180.2. Actions ΓòÉΓòÉΓòÉ

COLUMNS()               CREATE()
EXPRESSION()            GETNEXTROW()
GOTOTOP()               KEYS()
LOAD()                  SETEXPR()
SETKEYS()               SNAPSHOT()


ΓòÉΓòÉΓòÉ 180.2.1. COLUMNS() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇCOLUMNS(sqlcolnames,sqltypes,devcolnames,devtypes)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This operation fills parallel vector parameters with the names of columns or
their data types. All of the parameters except sqlcolnames are optional. Valid
in READ mode only.

Once a SETEXPR has been successfully completed, this statement returns the
selected information for each of the columns of the result of that query.

Note:   The column names returned in sqlcolnames are the DBM assigned names
        which may not be valid names for Visualizer columns and can differ from
        the names in devcolnames (also used for a SNAPSHOT or GETNEXTROW
        action).

The code below retrieves a list of columns and their datatypes in the current
SQL query.

CALL Trans1'COLUMNS(Columns[0],Types[0])


ΓòÉΓòÉΓòÉ 180.2.2. CREATE() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇCREATE(table,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                  ΓööΓöÇdestΓöÇΓöÿ

Creates an SQL base table using the Visualizer table identified in the TABLE
attribute as a template.  The name of the SQL table created must be provided as
the first parameter, therefore this SQL table must not already exist. The
operation, which is valid only in LOAD mode, takes no account of Visualizer
table keys in the creation of the SQL table. The created columns will match by
name and type to the Visualizer columns. The width is set to the largest width
of a column, or to the display width, whichever is greater.

The Visualizer data type to SQL data type mapping is as follows:

Visualizer SQL

Character VARCHAR(n), where n is specified to be either the display width of
          the Visualizer column or the length of the longest value in the
          column, whichever is greater.

Numeric   Scientific Notation. Note that from Visualizer there is no way to
          determine the numeric type further without end-user intervention.

Date      Date (ISO format)

Time      Time (ISO format)

Graphic   Graphic (with similar limitations as Character, above)

Remote platforms accessed from DDCS/2 can have different internal structures to
those of ES DBM or DB2/2. For DB2 systems, dest holds the destination database
and/or the tablespace.

To specify the database only (for example DATABASE MYDB):

CALL Trans2'CREATE("MYTAB","DATABASE MYDB")

To specify the database and tablespace:

CALL Trans1'CREATE("MYTAB","MYDB.MYTBS")

To specify the tablespace:

CALL trans'CREATE("MYTAB","MYTBS")

The database form is the default.

For SQL/DS, dest holds the destination space.

CALL trans'CREATE("MYTAB","MYDBSPC")

The code below creates the SQL table NEWTAB based on the contents of the
Visualizer table TEST opened with the handle TAB.

OPEN TABLE Tab,   !Assuming Trans'TABLE=Tab
 NAME     = "Test.TAB",
 LOCATION = "D:\TestData"

CALL Trans2'CREATE("NEWTAB")

Before you detach from a database, the logical unit of work must be completed
by an explicit COMMIT.  Otherwise, any changes to the database since the last
COMMIT will be lost by an implicit ROLLBACK.

Data sent to the SQL database must be committed before closing the database if
it is to persist:

CALL Session'COMMIT


ΓòÉΓòÉΓòÉ 180.2.3. EXPRESSION() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇEXPRESSION(vector)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This operation fills the vector parameter with the SQL select expression that
the object is working with. Valid only in READ mode, a valid expression only
exists once a SETEXPR action has been performed.

The following code retrieves the SQL query currently set in SLQTRANS object.
(The vector Expression will be created if it does not exist already.)

CALL Trans1'EXPRESSION(Expression[0])


ΓòÉΓòÉΓòÉ 180.2.4. GETNEXTROW() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇGETNEXTROW(ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                ΓööΓöÇvectorΓöÇΓöÿ

Reads one row resulting from the current SQL select expression and places the
row returned into:

o An ASL vector. If the name of the vector is inserted inside the parentheses,
  the values for each column in the resulting row are placed sequentially in
  the vector.
o A table specified by TABLE.  The resulting row is appended to the table.

After a GETNEXTROW() action, the current query remains set, and the next row
resulting from the query becomes available for reading. If a SNAPSHOT() action
is subsequently performed, the number of the remaining rows resulting from the
current query and specified by the SNAPSHOT are read. GETNEXTROW() is valid
only in READ mode after a SETEXPR action has completed successfully.
GETNEXTROW() after an end of file sets the error code to 9026.


ΓòÉΓòÉΓòÉ 180.2.5. GOTOTOP() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇGOTOTOP()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Resets the position of the next row to be read, either by a SNAPSHOT() or a
GETNEXTROW() action.  This allows all the rows resulting from the current query
to be read by a subsequent SNAPSHOT() action, including those already read by
previous GETNEXTROW() actions (the rows may be delivered in a different order
however) GOTOTOP() is valid only in READ mode after a SETEXPR action.

! Assumes SQLSESSION object "Session" is open
OPEN SQLTRANS Trans, Session,   ! Opens the SQLTRANS object
 MODE="R"

DEFINE selected[0]
INSERT selected[0]="SELECT * FROM STAFF"
! from SAMPLE database
CALL Trans'SETEXPR(selected[0])
!selected is the vector containing the SQL select statement.

CALL Trans'GETNEXTROW(sample[0])
! sample is the name of the vector into which the first row
! resulting from the query is placed.

CALL Trans'GOTOTOP()         ! Allows first result row to be reread.
MODIFY Trans,                ! Modifies the SQLTRANS object.
   TABLE = Tab,              ! Tab is the instance of an open
   MODE  = "R"               ! Table object.

CALL Trans'GETNEXTROW()      ! Places the first result row into
                             !  the open table.
CALL Trans'SNAPSHOT()        ! Places all the remaining result
                             ! rows into the open table.


ΓòÉΓòÉΓòÉ 180.2.6. KEYS() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇKEYS(vector)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

The names of the key columns that will be set on the Visualizer table are
returned in the vector provided. Either the names specified by SETKEYS or the
name specified by GENKEYCOL is returned in the vector parameter.

  CALL Trans'KEYS(KeyList[0])


ΓòÉΓòÉΓòÉ 180.2.7. LOAD() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇLOAD(table)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Valid only in LOAD mode, replaces the contents of an SQL table with those of a
Visualizer table. The number of columns in the tables must match, and the types
of each column must be compatible. (Compatibility means that each value must
match, or be convertible.) If partial data is read from SQL and then the LOAD
is performed, the old contents of the SQL table will be lost. The name of the
SQL table must be provided as a parameter, and the Visualizer table id used is
that in TABLE.

  CALL Trans'LOAD("NEWTAB")

Before you detach from a database, the logical unit of work must be completed
by an explicit COMMIT.  Otherwise, any data you sent to the database since the
last COMMIT will be lost by an implicit ROLLBACK.

Data sent to the SQL database must be committed before closing the database if
it is to persist:

CALL Session'COMMIT


ΓòÉΓòÉΓòÉ 180.2.8. SETEXPR() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSETEXPR(expression)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Takes a SELECT expression as input, as a scalar or vector of strings. The query
is given and the result becomes available for processing. If an expression was
previously set, then that expression is discarded and its associated resources
are freed. Valid in READ mode only.

The code below specifies an SQL query:

CALL Trans1'SETEXPR("SELECT * FROM STAFF")

If expression is a vector, then its elements are concatenated to give the final
expression.

Note:   To maintain a log of database access, provide a 32-bit DLL called
        SQLLOG.DLL in the LIBPATH. Every time SQL SELECT is issued, the
        following C function is called:

                void APIENTRY sqllog(unsigned char *,short)

This C function must log the SQL SELECT.

No error handling is provided for the logging process. If the DLL cannot be
loaded, then no error is reported and the SQL expression is processed normally.


ΓòÉΓòÉΓòÉ 180.2.9. SETKEYS() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSETKEYS(vector)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This operation identifies the columns that will form the key of the Visualizer
table generated by the SNAPSHOT operation.  The columns are identified by the
names that are returned in the result of the SQL query in the EXPRESSION
vector. (The names returned by the sqlcolnames parameter of the SQLTRANS
COLUMNS action). The order of the names in the vector is major key to minor
key. Valid only in READ mode after a SETEXPR action.

Note:   You cannot perform a SETKEYS action while the cursor is open as the
        destination Visualizer table for the SNAPSHOT or GETNEXTROW operation
        has already been prepared.

The code below creates a vector of columns to key the result table.  The SQL
column names can be different from the Visualizer column names.

DEFINE Keys[0]
INSERT Keys[0] = "ID"
CALL Trans'SETKEYS(Keys[0])
     ! Specify the keys to the SQLTRANS object


ΓòÉΓòÉΓòÉ 180.2.10. SNAPSHOT() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSNAPSHOT(number_of_rows)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action maps the result of an SQL query into a Visualizer table. The mode
of the object must be READ, a valid expression must have been set, and a valid
Visualizer table object id must be set in TABLE.  If  number_of_rows is
specified, that number of rows is passed into the Visualizer table. If the
number of rows is not specified, all rows are passed to the table.

Data types map as follows:

SQL       Visualizer
Char      Character
Varchar   Character
Smallint  Numeric
Integer   Numeric
Float or Real Numeric
Date      Date
Time      Time
Graphic   Graphic
Decimal   Numeric
Timestamp Character
Long varchar Character
Long vargraphic Character

Name conversion is done automatically. The names of the Visualizer columns may
need to be changed since SQL queries do not necessarily generate valid
Visualizer column names. (The names returned by COLUMNS can be either the SQL
or the Visualizer names.)

SNAPSHOT does not issue a commit itself after it has read the data. The
SNAPSHOT will however, change the location of the cursor. You may wish to issue
a COMMIT to free locks on the tables.

While the cursor is open, you can repeat the SNAPSHOT without providing a new
table ID. For the initial SNAPSHOT, the table must be empty.

SNAPSHOT to the end of file automatically resets the query so that the data can
be re-read into another Visualizer table without the need to perform another
SETEXPR.

Valid only in READ mode.

In the example below, 40 rows of the SQL result will be returned in the
Visualizer table.

CALL Trans1'SNAPSHOT(40)
A subsequent call with the same code will deliver the next 40 SQL result rows.
If a key has been set, the new rows may appear distributed within the table. If
a key has not been set, the new rows are appended to the end of the table.

Note:   You can abort a SNAPSHOT action after the operation has started by
        pressing Break more than six times while holding down the Ctrl key. The
        possibility of aborting the operation is implemented by six Ctrl
        Breaks. A subsequent Ctrl Break interrupts the SNAPSHOT action, closes
        the current query and resets the cursor.


ΓòÉΓòÉΓòÉ 180.3. More about SQLTRANS ΓòÉΓòÉΓòÉ

o In order to use SQLTRANS, you must have previously opened an SQLSESSION
  object. You can have more than one SQLTRANS object, but the number is limited
  by the resources used in the SQL database interface.

o The SQLTRANS object can have one of two modes, depending on the direction of
  the transfer. The object is controlling the transfer of data either from an
  SQL query to a Visualizer table (known as READ), or from a Visualizer table
  to an SQL base table (known as LOAD).

o The object provides the following function:

   - The ability to read the next n rows, n is selectable (see SNAPSHOT).

   - The ability to read rows individually, and if required, a number of the
     remaining rows.

   - Creation of SQL tables using Visualizer tables as a template.

   - The ability to replace the contents of an SQL table with those of a
     Visualizer table, deleting the existing SQL table, and replacing it with
     the Visualizer table.

o The SQLSESSION object is intended to persist over long periods, while the
  SQLTRANS object is intended to be used as a disposable object (used once for
  a specific transaction and then to be discarded).

  The SQLSESSION object is used to control the database while SQLTRANS is used
  to exchange data.

o The code below reads an SQL table (Q.STAFF assumed to exist in a database
  called DB2) into a Visualizer table called C:\TEST\SQLTEST.TAB

    !Open the SQL session
    OPEN SQLSESSION sqls,
     DRIVE  = 0,
     DBNAME = "DB2",
     STATUS = "S"

    !Open a new PRODUCT table
    OPEN TABLE Tab,
     NAME      = "SQLTEST.TAB",
     LOCATION  = "C:\TestData",
     MODE      = "WRITE"

    !Open the SQL transaction
    OPEN SQLTRANS Trans, sqls,
     TABLE = Tab,
     MODE  = "R"
    !Set up the SELECT statement
    CALL Trans'SETEXPR("SELECT * FROM Q.STAFF")

    !Retrieve the first 40 rows of the result
    CALL Trans'SNAPSHOT(40)

o The security of data within the SQL databases relies on the OS/2 DBM or DB2/2
  security. There is no provision for direct access to the control structures
  used within the interfaces. For additional information, refer to Database
  Manager Programmer's Guide and Reference or DB2/2 Information and Planning
  Guide


ΓòÉΓòÉΓòÉ 181. SQRT() ΓòÉΓòÉΓòÉ

The SQRT() function provides the square root of a number.

ΓöÇΓöÇSQRT(expression)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Examples

More about SQRT()


ΓòÉΓòÉΓòÉ 181.1. Examples ΓòÉΓòÉΓòÉ

LET x = SQRT(1764)                              ! Result is 42
LET x = SQRT(66)                                ! Result is 8.12

Examples source library:


ΓòÉΓòÉΓòÉ 181.2. More about SQRT() ΓòÉΓòÉΓòÉ

o An error is returned if expression gives a negative number, or if a
  nonnumeric value is used.


ΓòÉΓòÉΓòÉ 182. START ΓòÉΓòÉΓòÉ

The START statement causes a specified program to be loaded, and the ON START
block of the program to be executed immediately.

ΓöÇΓöÇSTARTΓöÇΓöÇtasktypeΓöÇΓöÇprogramalias,modulenameΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇ
                                              Γöé         <ΓöÇ,ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ   Γöé
                                              ΓööΓöÇ,START(ΓöÇΓöÇΓöÇparameterΓöÇΓö┤ΓöÇ)ΓöÇΓöÿ

Examples

More about START

See also: QUEUE PROGRAM, RUN PROGRAM, SIGNAL PROGRAM, STOP, WAIT PROGRAM


ΓòÉΓòÉΓòÉ 182.1. Examples ΓòÉΓòÉΓòÉ

START APPLICATION dlg1, "I.Modules.Dialogue"
START PROGRAM     dlg2, "I.Modules.Dialogue"
START PROGRAM     lion, "I.Modules.Fierce", START(POINTER(teeth[0]))

Examples source library:


ΓòÉΓòÉΓòÉ 182.2. More about START ΓòÉΓòÉΓòÉ

o A program can be active several times at once. The programalias enables you
  to refer to each version of the program separately.

o Once the ON START block of the newly started program has finished executing,
  control is returned to the statement after the START statement in the
  original program.


ΓòÉΓòÉΓòÉ 183. STDEV(), STDSAMP() ΓòÉΓòÉΓòÉ

The STDEV() and STDSAMP() functions return standard deviations.

STDEV() returns the standard deviation of a population of values. STDSAMP()
returns an estimate of the standard deviation based on a sample of values.

ΓöÇΓöÇSTDEV(array)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

ΓöÇΓöÇSTDSAMP(array)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Examples

More about STDEV() and STDSAMP()

See also: COUNT(), VARIANCE()


ΓòÉΓòÉΓòÉ 183.1. Examples ΓòÉΓòÉΓòÉ

dev = STDEV(set)
sdv = STDSAMP(sample_set)

Examples source library:


ΓòÉΓòÉΓòÉ 183.2. More about STDEV() and STDSAMP() ΓòÉΓòÉΓòÉ

o Any NULL or nonnumeric values in the array are ignored and the number of
  numeric values is adjusted accordingly. However, if the final number of
  numeric values falls below 2, an error is generated.

o STDSAMP() is calculated by summing the squared deviations of each value from
  the arithmetic mean, dividing by the number of values minus one, and taking
  the square root. STDEV() is calculated by summing the squared deviations of
  each value from the arithmetic mean, dividing by the number of values, and
  taking the square root.

o You can use the COUNT() function to provide the final sample size, and the
  VARIANCE() function to give the variance.


ΓòÉΓòÉΓòÉ 184. STOP ΓòÉΓòÉΓòÉ

The STOP statement in a program stops its execution and takes it out of an
active state.

          ΓöîΓöÇPROGRAMΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöÇΓöÇSTOPΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
          Γö£ΓöÇAPPLICATIONΓöÇΓöñ
          ΓööΓöÇMASTERΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

STOP terminates the APPLICATION, MASTER, or PROGRAM in which it is issued, with
all its related tasks. The default is STOP PROGRAM.

Examples

More about STOP


ΓòÉΓòÉΓòÉ 184.1. Examples ΓòÉΓòÉΓòÉ

ON ERROR
DO
  IF A.System.Event = "START"
  THEN STOP APPLICATION
END

ON STOP
  STOP

Examples source library:


ΓòÉΓòÉΓòÉ 184.2. More about STOP ΓòÉΓòÉΓòÉ

o STOP MASTER can be issued from a subtask. This stops the master task and its
  related subtasks.

o STOP APPLICATION can be issued from a subtask or master task. This stops the
  application and its related subtasks.

o STOP PROGRAM is the default. This stops the current program and any related
  subtasks.


ΓòÉΓòÉΓòÉ 185. STREAM ΓòÉΓòÉΓòÉ

STREAM does not refer to a single object class, but to behavior implemented by
the SMEMORY and SFILE objects. Stream classes are used to facilitate data
exchange with other programs.

SMEMORY is based on a contiguous area of memory.

SFILE is based on an OS/2 file.

Attributes

Actions

Events

See also: DDESERVER, DDECLIENT, REFERENCE,


ΓòÉΓòÉΓòÉ 185.1. Attributes ΓòÉΓòÉΓòÉ

CODE                  FORMAT
LINK                  LOCATION
MODE                  NAME
OBJECTNAME            ORIGINATOR
POINT                 REFERENCE
SIZE                  STATUS
TYPE


ΓòÉΓòÉΓòÉ 185.1.1. CODE ΓòÉΓòÉΓòÉ

This read-only attribute will reflect the success or failure of the last
operation. It may have a value specific to STREAM, such as when a GETASL action
fails due to invalid data being in the STREAM, or it may be an error value
returned from the operating system in response to file I/O, memory allocation,
etc.


ΓòÉΓòÉΓòÉ 185.1.2. FORMAT ΓòÉΓòÉΓòÉ

This attribute may be set on OPEN and then subsequently queried. It indicates
the format of the data to be delivered to or accepted from the STREAM. Possible
values might be "DIF", "IXF", "Metafile", "Bitmap", etc.

If the STREAM is delivered by a SOURCE event, then FORMAT indicates the format
in which the data should be given to the STREAM. If the STREAM is delivered by
a TARGET event, then FORMAT indicates the format of data to be extracted from
the STREAM.

The STREAM makes no attempt to verify that data conforms to the specified
format, this is an application responsibility.


ΓòÉΓòÉΓòÉ 185.1.3. LINK ΓòÉΓòÉΓòÉ

This attribute indicates, when 1 (true), that the data within the STREAM is
link information. Use the LINK object to access the information.

Default: 0 (False) Set on OPEN, then read/write


ΓòÉΓòÉΓòÉ 185.1.4. LOCATION ΓòÉΓòÉΓòÉ

This attribute can be set to a valid file location. If LOCATION is omitted,
then a default unique location is generated and returned whenever LOCATION is
queried.

Default: None Set on OPEN, then read-only.


ΓòÉΓòÉΓòÉ 185.1.5. MODE ΓòÉΓòÉΓòÉ

The access mode of the STREAM. If the STREAM is delivered by a TARGET event,
then MODE has a value of READ-data can only be read from the object. If the
STREAM is delivered by a SOURCE event, or if it is opened directly, then MODE
has a value of WRITE.

MODE may be modified to allow one object to open a STREAM, populate it with
data, and then pass it on to another object in read-only mode. Modifying MODE
resets the value of POINT to 0.

If MODE is modified to a value other than "READ" or "WRITE", an error condition
will be raised. If MODE is set to "WRITE" when the STREAM is an SFILE mapped to
a write protected file, an error condition will be raised.


ΓòÉΓòÉΓòÉ 185.1.6. NAME ΓòÉΓòÉΓòÉ

This attribute indicates the name of the data to be delivered or accepted from
the STREAM.

Default: None Set on OPEN, then read-only. (If NAME is omitted, a default
unique name will be generated and returned whenever NAME is queried.)


ΓòÉΓòÉΓòÉ 185.1.7. OBJECTNAME ΓòÉΓòÉΓòÉ

This attribute provides qualifying information to a target when a drop occurs.

When a drop occurs this attribute will match the OBJECTNAME attribute of the
SOURCECTRL object.

Default: None


ΓòÉΓòÉΓòÉ 185.1.8. ORIGINATOR ΓòÉΓòÉΓòÉ

This attribute may be set on OPEN and then subsequently queried. It identifies
the object which generated the event through which the STREAM was delivered.

If the SOURCE or TARGET event may have been generated by several different
means, then you can use the ORIGINATOR attribute to distinguish between them.


ΓòÉΓòÉΓòÉ 185.1.9. POINT ΓòÉΓòÉΓòÉ

This attribute signifies the current point within the data, that the next read
or write operation would begin from, 0 being the beginning of the data.

POINT may be queried or modified. Point must be an integer value greater than
or equal to zero, if modified to any other value an error condition will be
raised.

If POINT is modified to a value greater than the current value of SIZE, it will
be set to the current value of SIZE, no error will result.


ΓòÉΓòÉΓòÉ 185.1.10. REFERENCE ΓòÉΓòÉΓòÉ

If a target application has established that it can only accept a reference to
a particular data format, then this attribute is set to 1 (true) when that
format is delivered by a TARGET event.

The application should then open a REFERENCE object and pass it the STREAM
holding the reference information. Query the attributes of the REFERENCE object
for details of the reference data.


ΓòÉΓòÉΓòÉ 185.1.11. SIZE ΓòÉΓòÉΓòÉ

This read-only attribute will reflect the total number of bytes of data within
the STREAM.


ΓòÉΓòÉΓòÉ 185.1.12. STATUS ΓòÉΓòÉΓòÉ

This attribute is initialized to 0 when delivered by a SOURCE event or by a
TARGET event. You can modify it or query it. It is used to indicate success or
failure of the event.

If errors occur extracting or delivering data to the STREAM, then the STATUS
attribute should be set to an integer between 1 and 255 prior to SHUTting the
STREAM.


ΓòÉΓòÉΓòÉ 185.1.13. TYPE ΓòÉΓòÉΓòÉ

The type of the object that is being dragged (or has been dropped). The
OBJECTNAME attribute may have additional qualifying information about the
object. TYPE is set when an object is dropped on the application as a result of
type matching.

Default: None Set on OPEN, then read/write


ΓòÉΓòÉΓòÉ 185.2. Actions ΓòÉΓòÉΓòÉ

PUTASL()              GETASL()
PUTLINE()             GETLINE()
PUTDATA()             GETDATA()
FINISHED()


ΓòÉΓòÉΓòÉ 185.2.1. PUTASL() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇPUTASL(variable,start,number)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action populates the STREAM with ASL data, preserving ASL attribute
information.

variable may be a scalar or vector, declared or otherwise. start, if specified,
is the first element to be taken from the vector. The value may be any positive
integer, the default being 1. number, if specified, is the number of elements
to be taken from a vector. The value may be any positive integer greater than
0, if unspecified it defaults to all remaining elements.

If variable is a scalar, subsequent parameters are ignored. If it is a vector,
and start is greater than the bounds of the vector, an error will result. If it
is a vector, and start plus number minus 1 is greater than the bounds of the
vector, an error will result. If MODE is not "WRITE", an error will result.

Failure to complete this action due to environment errors such as disk full or
unable to allocate memory, will result in an error condition.


ΓòÉΓòÉΓòÉ 185.2.2. GETASL() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇGETASL(variable,number)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action populates an ASL variable with data from the STREAM. The data in
the STREAM must have been created via the PUTASL action, otherwise the results
will be unpredictable.

variable may be a scalar or vector, declared or otherwise. number, if
specified, is the number of ASL values to be read from the STREAM. The value
may be any positive integer greater than 0, if unspecified it defaults to all
remaining data in the STREAM.

If variable is a scalar, number is ignored. If it is strongly typed, the
value(s) being retrieved must conform to the type of the variable, otherwise an
error will result. If it is a declared vector, and number exceeds the bounds of
the vector, excess data is discarded without an error condition. If it is an
undeclared vector, the vector is expanded as necessary to accommodate the
values, within system limits. If system limits are met, excess data is
discarded without an error.

It is incumbent upon the client to ensure that the data being requested is
suitable for the target variable.


ΓòÉΓòÉΓòÉ 185.2.3. PUTLINE() ΓòÉΓòÉΓòÉ

                      ΓöîΓöÇ1ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöÇΓöÇPUTLINE(variable,ΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇ,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                      ΓööΓöÇstartΓöÇΓöÿ   ΓööΓöÇnumberΓöÇΓöÿ

This action populates the STREAM with ASCII data, inserting CRLF X'0D0A' ASCII
codes after each value. Character conversion is performed on non character
values prior to delivery to the STREAM.

variable may be a scalar or vector, declared or otherwise. start, if specified,
is the first element to be taken from a vector. The value may be any positive
integer, the default being 1. number, if specified, is the number of elements
to be taken from a vector. The value may be any positive integer greater than
0, if unspecified it defaults to all remaining elements.

If variable is a scalar, subsequent parameters are ignored. If it is a vector,
and start is greater than the bounds of the vector, an error will result. If it
is a vector, and start plus number minus 1 is greater than the bounds of the
vector, an error will result. If MODE is not "WRITE", an error will result.

Failure to complete this action due to environment errors such as disk full or
unable to allocate memory, will result in an error condition.


ΓòÉΓòÉΓòÉ 185.2.4. GETLINE() ΓòÉΓòÉΓòÉ

                                    ΓöîΓöÇ1ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöÇΓöÇGETLINE(variable,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ,ΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                      ΓööΓöÇrecordsΓöÇΓöÿ   ΓööΓöÇsplitΓöÇΓöÿ

This action populates an ASL variable with data from the STREAM. The data in
the STREAM is delimited based on encountering CRLF X'0D0A' ASCII codes.

variable may be a scalar or vector, declared or otherwise. records, if
specified, is the number of delimited values to be read from the STREAM. The
value may be any positive integer greater than 0, if unspecified it defaults to
all remaining data in the STREAM.

split is a Boolean value, optionally provided by the caller, that controls the
behavior if the data contains delimited values greater than 255 bytes. If
specified as 1 (the default), values greater than 255 bytes are split into 255
byte blocks to populate multiple elements of variable. With split set to 1,
variable may be populated with more elements than records. If specified as 0,
data in excess of 255 bytes is discarded. A subsequent GETLINE request will
read from the beginning of the next delimited value.

In the event of delimited values greater than 255 bytes being encountered,
GETLINE will return a value of 1, otherwise it will return 0. Where the length
of delimited values is unknown, yet data loss must be avoided, the safest
approach is to use GETLINE with variable as an undeclared vector, and records
and split both set to 1.

If variable is a scalar, records is ignored. If it is declared or strongly
typed, the value(s) being retrieved must be able to be converted to the type of
the variable, otherwise an error will result. If it is a declared vector, and
records exceeds the bounds of the vector, excess data is discarded without an
error condition. If it is an undeclared vector, the vector is expanded as
necessary to accommodate the values, within system limits. If system limits are
met, excess data is discarded without an error.

It is incumbent upon the client to ensure that the data being requested is
suitable for the target variable.


ΓòÉΓòÉΓòÉ 185.2.5. PUTDATA() ΓòÉΓòÉΓòÉ

                      ΓöîΓöÇ1ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöÇΓöÇPUTDATA(variable,ΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇ,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                      ΓööΓöÇstartΓöÇΓöÿ   ΓööΓöÇelementsΓöÇΓöÿ

This action populates the STREAM with ASCII data. Character conversion is
performed on noncharacter values prior to delivery to the STREAM.

variable may be a scalar or vector, declared or otherwise. start, if specified,
is the first element to be taken from a vector. The value may be any positive
integer, the default being 1. elements, if specified, is the number of elements
to be taken from a vector. The value may be any positive integer greater than
0, if unspecified it defaults to all remaining elements.

If variable is a scalar, subsequent parameters are ignored. If it is a vector,
and start is greater than the bounds of the vector, an error will result. If it
is a vector, and start plus elements minus 1 is greater than the bounds of the
vector, an error will result. If MODE is not "WRITE", an error will result.

Failure to complete this action due to environment errors such as disk full or
unable to allocate memory, will result in an error condition.


ΓòÉΓòÉΓòÉ 185.2.6. GETDATA() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇGETDATA(variable,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                      ΓööΓöÇbytesΓöÇΓöÿ

This action populates an ASL variable with data from the STREAM.

variable may be a scalar or vector, declared or otherwise. bytes, if specified,
is the number of bytes to be read from the STREAM. The value may be any
positive integer greater than 0, if unspecified it defaults to all remaining
data in the STREAM.

variable must be character or untyped, otherwise an error will result. If it is
a scalar, and bytes exceeds 255, excess data is discarded without an error. If
it is a vector, and bytes exceeds 255, the data is split into 255 byte blocks
and assigned to elements of the vector. If it is a declared vector, and bytes
divided by 255 exceeds the bounds of the vector, excess data is discarded
without an error condition. If it is an undeclared vector, the vector is
expanded as necessary to accommodate the data, within system limits. If system
limits are met, excess data is discarded without an error.


ΓòÉΓòÉΓòÉ 185.2.7. FINISHED() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇFINISHED()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action signifies to the STREAM that all its data has been read, or that
population of it is complete. On receipt, STREAM will inform the object that
created it (provided ORIGINATOR has been set).

The STREAM should always be SHUT after its FINISHED() action has been called.


ΓòÉΓòÉΓòÉ 185.3. Events ΓòÉΓòÉΓòÉ

ERROR

Usage exceptions are outlined under actions.

The STREAM object in question should have its STATUS attribute set according to
the error, its FINISHED() action called, and then SHUT the STREAM.


ΓòÉΓòÉΓòÉ 186. STRING ΓòÉΓòÉΓòÉ

The STRING graphics primitive object class creates an instance of a text
string.

Parent: DEFINE

Attributes

Actions: None.

Events: None.

Examples


ΓòÉΓòÉΓòÉ 186.1. Attributes ΓòÉΓòÉΓòÉ

ALIGNMENT             ANGLE
CELLX                 CELLY
DIRECTION             FONT
HORZJUST              MULTILINE
REFERENCE             SHEAR
SIZE

The following standard graphics attributes are also available. They are
described in Standard graphics attributes:

COLOR                 MIX
SELECTED              VISIBLE
CONSTANT              SELECTABLE


ΓòÉΓòÉΓòÉ 186.1.1. ALIGNMENT ΓòÉΓòÉΓòÉ

Alignment of the text string:

1         Bottom left
2         Bottom center
3         Bottom right
4         Center left
5         Center
6         Center right
7         Top left
8         Top center
9         Top right

Default: 1 (Bottom left)


ΓòÉΓòÉΓòÉ 186.1.2. ANGLE ΓòÉΓòÉΓòÉ

Angle of the baseline relative to the axis.

Default: 0


ΓòÉΓòÉΓòÉ 186.1.3. CELLX ΓòÉΓòÉΓòÉ

Width of a character box in world coordinate units.

Default: Defined at run time, device dependent


ΓòÉΓòÉΓòÉ 186.1.4. CELLY ΓòÉΓòÉΓòÉ

Height of a character box in world coordinate units.

Default: Defined at run time, device dependent


ΓòÉΓòÉΓòÉ 186.1.5. DIRECTION ΓòÉΓòÉΓòÉ

Direction of the baseline:

1 or 0    Left to right
2         Bottom to top
3         Right to Left
4         Top to bottom

Default: 0 (Left to right)


ΓòÉΓòÉΓòÉ 186.1.6. FONT ΓòÉΓòÉΓòÉ

An integer that specifies the font to be used. To specify the typeface, use one
of the following:

0         Standard (Latin-1 character set only)
1         Courier
2         Tms Rmn
3         Helv
64        Mincho (DBCS)
96        Gothic (DBCS)

To specify a style other than Normal, add one or more of the following:

1         Medium (only for DBCS fonts)
4         Outline
8         Bold (not available with Medium)
16        Italic

For example, to specify Helv Bold Italic, use 27 (that is, 3 + 8 + 16). To
specify Mincho Medium Outline, use 69 (that is, 64 + 1 + 4).

You can specify Medium only with the DBCS fonts Mincho and Gothic. Specifying
Medium Bold is the same as just specifying Medium.

If the font you specify is not valid or not installed, then the font defaults
to 0 (currently Standard Normal).

Default: 0 (Currently Standard)


ΓòÉΓòÉΓòÉ 186.1.7. HORZJUST ΓòÉΓòÉΓòÉ

Horizontal alignment of string:

0         Left aligned
1         Right aligned
2         Centered

Default: 0 (Left aligned)


ΓòÉΓòÉΓòÉ 186.1.8. MULTILINE ΓòÉΓòÉΓòÉ

Permits display of multiple lines of text:

0         Single line only displayed (the third element of the REFERENCE
          vector)
1         Multiple lines displayed (fourth and subsequent elements of the
          REFERENCE vector)

Default: 0 (Single line only)


ΓòÉΓòÉΓòÉ 186.1.9. REFERENCE ΓòÉΓòÉΓòÉ

Vector defining the start point of the string and the text of the string
itself. This vector consists of the following elements:

1         X coordinate of the start of the string
2         Y coordinate of the start of the string
3         Text of the first string
4         Text of the second string

Multiple strings can be displayed only if the MULTILINE attribute is set. All
coordinates are in world coordinate units.

Set on OPEN, then read-only

Default: ""


ΓòÉΓòÉΓòÉ 186.1.10. SHEAR ΓòÉΓòÉΓòÉ

Angle of upright strokes relative to the vertical baseline.

Default: 0


ΓòÉΓòÉΓòÉ 186.1.11. SIZE ΓòÉΓòÉΓòÉ

Scale of the text, relative to the standard character cell size.

Default: 1


ΓòÉΓòÉΓòÉ 186.2. Examples ΓòÉΓòÉΓòÉ

DEFINE array[3]
LET array[1] = 30               ! X position
LET array[2] = 120              ! Y position
LET array[3] = "Graphic String" ! string text
OPEN STRING string, def1,
 REFERENCE = array[0],
 CELLX = 50,
 CELLY = 50,
 FONT = 2,
 COLOR = "Red"

Examples source library:


ΓòÉΓòÉΓòÉ 187. STRING() ΓòÉΓòÉΓòÉ

The STRING() function is used to build a string using embedded expressions.

ΓöÇΓöÇSTRING(textΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                Γöé <ΓöÇ,ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ Γöé
                ΓööΓöÇΓöÇΓöÇexpressionΓöÇΓö┤ΓöÇΓöÿ

Examples

More about STRING()


ΓòÉΓòÉΓòÉ 187.1. Examples ΓòÉΓòÉΓòÉ

x = STRING("_fish","Gold")         ! "Goldfish".
x = STRING("As simple as _","ABC") ! "As simple as ABC".

line = A.System.ErrorLine
num  = A.System.ErrorNumber[1]
info = A.System.ErrorInfo[1]
msg  = STRING("Error _ (^) at line _", num, info, line )
       ! "Error 2830 ('CODE') at line 8"

x = "'__' said the clown"
x = STRING( x, "Aha", "!" )       /* "'Aha!' said the clown". */

Examples source library:


ΓòÉΓòÉΓòÉ 187.2. More about STRING() ΓòÉΓòÉΓòÉ

o If an underscore in text is followed directly by a single digit, it refers
  explicitly to the corresponding expression. The digit does not appear in the
  resulting text string. For example:

    t[1] = "Error _1 at line _2"
    t[2] = "Line _2 caused error _1"
    t[3] = "Linea _2 erratum _1 causavit"
    msg  = STRING( t[1], num, line )  ! "Error 2830 at line 8"
    msg  = STRING( t[2], num, line )  ! "Line 8 caused error 2830"
    msg  = STRING( t[3], num, line )  ! "Linea 8 erratum 2830 causavit"

o Any optional expressions which do not have a corresponding underscore in text
  are added at the end of text when it is displayed.

o Excess underscores in text are left unchanged in the prompt displayed.

o Any NULL values that should replace an underscore are inserted in displayable
  format.


ΓòÉΓòÉΓòÉ 188. SYSTEM ΓòÉΓòÉΓòÉ

The SYSTEM object allows access to facilities provided by OS/2.

Attributes

Actions

Events

Examples


ΓòÉΓòÉΓòÉ 188.1. Attributes ΓòÉΓòÉΓòÉ

CODE                  CDIR
CDRIVE                RETURNCODE


ΓòÉΓòÉΓòÉ 188.1.1. CODE ΓòÉΓòÉΓòÉ

Most recent operating system return code.

Read-only.


ΓòÉΓòÉΓòÉ 188.1.2. CDIR ΓòÉΓòÉΓòÉ

Name of the current directory.

Can be queried or modified.


ΓòÉΓòÉΓòÉ 188.1.3. CDRIVE ΓòÉΓòÉΓòÉ

Name of the current drive.

Can be queried or modified.


ΓòÉΓòÉΓòÉ 188.1.4. RETURNCODE ΓòÉΓòÉΓòÉ

Code that the Visualizer EXE returns when it ends (provided no other
application modifies this attribute).

Can be queried or modified.

Default: 0


ΓòÉΓòÉΓòÉ 188.2. Actions ΓòÉΓòÉΓòÉ

ATTRIB()                   COMMAND()
COMMANDCODE                CREATETEMP()
COPY()                     EXCLUDETEMP()
DELETE()                   DELETETEMP()
DIRECTORIES()              DRIVES()
FILE()                     FILES()
INCLUDETEMP()              PRINTREQUEST()
QUERYTEMP()                RENAME()
SEARCHPATH()               QUERYCLASS()
SETOBJECTDATA()


ΓòÉΓòÉΓòÉ 188.2.1. ATTRIB() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇATTRIB(file,attribute,set)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Changes an attribute of file. attribute can be one of the following:

"R"       Read-only
"A"       Archive
"H"       Hidden.
set controls whether the attribute is cleared or set:

0         Clears the attribute
1         Sets the attribute.

The default value is 1, which sets the attribute.


ΓòÉΓòÉΓòÉ 188.2.2. COMMAND() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇCOMMAND(ΓöÇΓö¼ΓöÇComStringΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
             ΓööΓöÇComVec[0]ΓöÇΓöÿ

If you specify ComString, then it is is the operating system command to be
executed. If you specify ComVec[0], then the elements of the vector ComVec are
concatenated to form the operating system command to be executed.

This action uses the Command Line Interpreter to execute the command, so
special characters such as &, <, and > can be used.

The action is synchronous and waits until the command has completed before it
returns.

The OS/2 START command may be used to cause a command to run asynchronously.
In this case, the command needs to terminate the process that it is running in,
so it is only suitable for commands that interact with the user or commands
(typically REXX) that issue an explicit EXIT. Using START will allow the
command to run in a session of its own with a full screen window.  Some
programs will only run asynchronously and must be used with the START command.

COMMAND() raises ERROR if the Command Line Interpreter reports any error. The
return code is available in the CODE attribute of the SYSTEM object. COMMAND()
always returns NULL.


ΓòÉΓòÉΓòÉ 188.2.3. COMMANDCODE() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇCOMMANDCODE(ComString)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

The same as COMMAND(), but returns the Command Line Interpreter return code.
COMMANDCODE() does not raise ERROR if the return code is nonzero.


ΓòÉΓòÉΓòÉ 188.2.4. CREATETEMP() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇCREATETEMP()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Creates a temporary file and returns its name. Such temporary files are deleted
when the application ends.


ΓòÉΓòÉΓòÉ 188.2.5. COPY() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇCOPY(file1,file2)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Copies from file1 to file2. file1 must be a fully qualified file name. If file1
is a table, it must be closed before beginning the copy. If file2 exists, it
must not be read-only or currently in use.


ΓòÉΓòÉΓòÉ 188.2.6. EXCLUDETEMP() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇEXCLUDETEMP(file)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

file is removed from the list of files to delete automatically when the
application ends.


ΓòÉΓòÉΓòÉ 188.2.7. DELETE() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇDELETE(file)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Deletes file file. file is the name and location of the file to be deleted.


ΓòÉΓòÉΓòÉ 188.2.8. DELETETEMP() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇDELETETEMP(file)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Deletes the temporary file named file.


ΓòÉΓòÉΓòÉ 188.2.9. DIRECTORIES() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇDIRECTORIES(vector,location)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

vector is a vector which is filled with a list of the subdirectories in the
directory identified by location.


ΓòÉΓòÉΓòÉ 188.2.10. DRIVES() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇDRIVES(vector)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

vector is a vector which is filled with a list of available drives in the form
"A:", "C:".


ΓòÉΓòÉΓòÉ 188.2.11. FILE() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇFILE(vector,location,filename)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

vector is a vector which is filled with a list of items of information about
the file filename in the directory location. The vector elements are:

1         File name, including the extension but excluding the location
2         "R" or "W", indicating whether the file can be written
3         File size, in bytes
4         Date of last write
5         Time of last write
6         Date of last read
7         Time of last read
8         Date of creation
9         Time of creation.

Items not available are included in the vector as nulls.


ΓòÉΓòÉΓòÉ 188.2.12. FILES() ΓòÉΓòÉΓòÉ

                                  ΓöîΓöÇ"*"ΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöÇΓöÇFILES(vectorΓöÇΓöÇ,ΓöÇΓöÇlocationΓöÇΓöÇ,ΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇ,ΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                                  ΓööΓöÇfilterΓöÇΓöÿ      ΓööΓöÇclassesΓöÇΓöÿ

vector is a vector which is filled with a list of the files in the directory
identified by location.

filter is optional. If filter is specified, it is used as a mask to filter out
the files listed. If filter is omitted, "*" is assumed.

classes is optional. If classes is specified, then it is a vector used as a
mask to get an objectlist of a specified object or objects. If classes is
omitted, then all objects are listed. The classes value for the object is
indicated by the extended attribute of the object in the directory.

Directories, hidden files, and system files are not listed.


ΓòÉΓòÉΓòÉ 188.2.13. INCLUDETEMP() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇINCLUDETEMP(file)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

file is added to the list of files to delete automatically when the application
ends.


ΓòÉΓòÉΓòÉ 188.2.14. PRINTREQUEST() ΓòÉΓòÉΓòÉ

                                               ΓöîΓöÇ1ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöÇΓöÇPRINTREQUEST(ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ,ΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                  ΓööΓöÇprinternameΓöÇΓöÿ   ΓööΓöÇnameΓöÇΓöÿ   ΓööΓöÇdialogΓöÇΓöÿ

PRINTREQUEST will open a PRINTER object and set the objects DESCRIPTION
attribute to the selected printer (the default system printer or one selected
from a dialog).

printername, if specified, should match one of the Workplace Shell defined
printers.

If printername is specified as "*", the Workplace Shell default printer is
assumed. If printername is not specified or there is no default printer, a list
of printers is presented to the user (subject to the setting of Dialog).

dialog controls the presentation of dialogs. The default is 1, but the
parameter can be set to 0 to suppress the presentation of dialogs.  If the
dialog is suppressed, the default printer specified in Print Manager is used.

If specified, Name should match the instance name of the calling application.
It is used to construct the title of the printer selection dialog. It may be a
character string of up to 255 bytes. If not specified, the default title of
Printer selection will be used.

After the PRINTREQUEST action has been issued (and any dialogs closed), a PRINT
event is signaled. The PRINT event is passed the handle to the open PRINTER
object.


ΓòÉΓòÉΓòÉ 188.2.15. QUERYTEMP() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇQUERYTEMP(file)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Returns 1 if file is in the list of temporary files that are deleted when the
application ends. Returns 0 if file is not in the list.


ΓòÉΓòÉΓòÉ 188.2.16. RENAME() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇRENAME(file1,file2)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Renames file1 to file2.


ΓòÉΓòÉΓòÉ 188.2.17. SEARCHPATH() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSEARCHPATH(file,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                     ΓööΓöÇpathvariableΓöÇΓöÿ

Searches a path variable for the presence of file and returns its location. If
pathvariable is specified, it is the name of an OS/2 environment variable set
by the SET command to the path which is to be searched.  If pathvariable is not
specified, the standard installation path is searched.


ΓòÉΓòÉΓòÉ 188.2.18. QUERYCLASS() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇQUERYCLASS(class)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Queries whether an object class is installed. class is a string containing the
name of the object class, for example "IBMCHART". Returns either true (nonzero)
meaning that the object class is installed, or false (zero) meaning that the
object class is not installed.


ΓòÉΓòÉΓòÉ 188.2.19. SETOBJECTDATA() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSETOBJECTDATA(wp_objectid,wp_setupstring)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

SETOBJECTDATA() passes a Workplace Shell setup string to an object. Identify
the object either by its ID enclosed in angle brackets ( <>), or by its file
name.

SETOBJECTDATA() is the same as the REXXUTIL function SysSetObjectData, but
SETOBJECTDATA() does not rely on REXX being installed.

For example, you can use SETOBJECTDATA() to associate an icon to a file.

You can also use SETOBJECTDATA() to open a view of an object, automatically
resurfacing an existing view if there is one, like this:

OPEN SYSTEM Sys
CALL Sys'SETOBJECTDATA("D:\MyFolder", "OPEN=DEFAULT")


ΓòÉΓòÉΓòÉ 188.3. Events ΓòÉΓòÉΓòÉ

PRINT


ΓòÉΓòÉΓòÉ 188.3.1. PRINT ΓòÉΓòÉΓòÉ

Signaled by the PRINTREQUEST() action.


ΓòÉΓòÉΓòÉ 188.4. Examples ΓòÉΓòÉΓòÉ

OPEN SYSTEM sys                ! Open the SYSTEM object

CALL sys'DRIVES( drivelist )   ! List available drives

CALL sys'DIRECTORIES(
 directorylist,                ! List directories
 sys'cdrive )                  ! on the current drive

CALL sys'FILES(
 filelist,                     ! List files
 sys'CDRIVE || sys'CDIR )      ! in the current directory

tempname=sys'CREATETEMP()      ! Create a temporary file
CALL COPYTAB( tempname, 'EMPDATA', sys'SEARCHPATH( 'EMPDATA' ))
CALL sys'DELETETEMP(tempname)  ! Delete the temporary file

SHUT sys                       ! Shut the system object
The example below executes an operating system command for directory of all
files with the extension C and redirects the output to a file.

FORGIVE CALL sys'COMMAND( "DIR *.C >file" )
FORGIVE CALL sys'DELETE( "file" )

Using START allows command to run in a session of its own with a full screen
window.

CALL sys'COMMAND ( "START myprog /s" )

The example below shows how to select a list of objects where the objects
included are restricted to those contained in a passed vector.

DEFINE classes[1] = "IBMTABLE"
OPEN SYSTEM os2
CALL os2'Files(Vector, ".","*",classes)

Examples source library:


ΓòÉΓòÉΓòÉ 189. TAB() ΓòÉΓòÉΓòÉ

The TAB() function returns a format value which specifies that tab characters
are required in the output. Only devices which support lines of output (such as
a printer) are suitable destinations for the format value.

ΓöÇΓöÇTAB(expression)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Examples

See also: LINE(), PAGE(), POSITION(), PRINTER, SPACE()


ΓòÉΓòÉΓòÉ 189.1. Examples ΓòÉΓòÉΓòÉ

CALL Printer'PUT("Pages:",TAB(3),Totpage)

Examples source library:


ΓòÉΓòÉΓòÉ 190. TABLE ΓòÉΓòÉΓòÉ

The TABLE object class provides access to user data tables.

Attributes

Actions

Events: None.

Examples

See also: IBMDATA, VIEWROWS, VIEWCALCS, VIEWORDER, VIEWTABLES


ΓòÉΓòÉΓòÉ 190.1. Attributes ΓòÉΓòÉΓòÉ

CODE                   COLUMNS
COMMENT                KEEP
KEYED                  KEYS
LOCATION               MODE
NAME                   OBJECTCLASS
PREFIX                 ROWS
TYPE


ΓòÉΓòÉΓòÉ 190.1.1. CODE ΓòÉΓòÉΓòÉ

Most recent operating system or internal error code.

Can be queried but not modified.

Default: None


ΓòÉΓòÉΓòÉ 190.1.2. COLUMNS ΓòÉΓòÉΓòÉ

Total number of columns.

Read-only.

Default: 0 (For a new table)


ΓòÉΓòÉΓòÉ 190.1.3. COMMENT ΓòÉΓòÉΓòÉ

A comment stored with the table. This is displayed (and can be changed) when
the table is edited using the table editor.

Default: None


ΓòÉΓòÉΓòÉ 190.1.4. KEEP ΓòÉΓòÉΓòÉ

Whether the table is to be kept after it is SHUT (by all end users).

0         Temporary tables
1         Permanent tables

Set on OPEN, then modifiable

Default: 1 (Permanent tables)


ΓòÉΓòÉΓòÉ 190.1.5. KEYED ΓòÉΓòÉΓòÉ

Whether the table has keys or is unkeyed:

0         Unkeyed
1         Keyed

Read-only.

Default: 0 (For a new table)


ΓòÉΓòÉΓòÉ 190.1.6. KEYS ΓòÉΓòÉΓòÉ

Number of key columns, up to a maximum of 16. Only meaningful if KEYED is set.
The number of key columns is set using the SETKEYS() action.

Read-only.

Default: None


ΓòÉΓòÉΓòÉ 190.1.7. LOCATION ΓòÉΓòÉΓòÉ

Location of the file (its OS/2 path).

Set on OPEN, then read-only.

Default: None


ΓòÉΓòÉΓòÉ 190.1.8. MODE ΓòÉΓòÉΓòÉ

Sets the access mode:

"READ"    Opened with read-only access.

"WRITE"   Opened with read and write access.

"ASAP"    Opened with ASAP access (data is written back to disk as soon as
          possible).

          Note:   This causes a very significant decrease in performance when
                  using large tables or tables in remote nodes on a LAN. Where
                  performance is critical, use the WRITE access mode instead of
                  ASAP.


Read-only after creation.

Default: "READ"


ΓòÉΓòÉΓòÉ 190.1.9. NAME ΓòÉΓòÉΓòÉ

Name of the file which is to hold the table.

Set on OPEN, then read-only.

Default: None


ΓòÉΓòÉΓòÉ 190.1.10. OBJECTCLASS ΓòÉΓòÉΓòÉ

External class name of the table. Refers to the .TYPE attribute of the OS/2
file that the table is held as. Set it to "IBMTABLE" to get the table listed in
Visualizer selection lists of tables.

Default: None


ΓòÉΓòÉΓòÉ 190.1.11. PREFIX ΓòÉΓòÉΓòÉ

Prefix (that is, the first part of the name) to be used when referring to
columns of the table.

Set on OPEN, then read-only.

Default: Last part of the name of the object used in the OPEN statement to
represent the table


ΓòÉΓòÉΓòÉ 190.1.12. ROWS ΓòÉΓòÉΓòÉ

Number of rows. Only meaningful if KEYED is set.

Read-only.

Default: 0 (For a new table)


ΓòÉΓòÉΓòÉ 190.1.13. TYPE ΓòÉΓòÉΓòÉ

Type of table:

"PERM"    Permanent.  Saved to disk at once.
"TEMP"    Temporary. Saved to disk only when shut (if KEEP=1)..

Set on OPEN, then read-only.

Default: "PERM"


ΓòÉΓòÉΓòÉ 190.2. Actions ΓòÉΓòÉΓòÉ

CHECKPOINT()            COLUMNS()
KEYS()                  NOKEYS()
SETKEYS()               SAVETO()


ΓòÉΓòÉΓòÉ 190.2.1. CHECKPOINT() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇCHECKPOINT()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Ensures that a table is up to date on disk. This only applies to tables opened
for WRITE. READ tables cannot be modified. ASAP tables are checkpointed
automatically after every modification.


ΓòÉΓòÉΓòÉ 190.2.2. COLUMNS() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇCOLUMNS(colv)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

colv is a vector to be filled with the names of the columns of the table.


ΓòÉΓòÉΓòÉ 190.2.3. KEYS() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇKEYS(colv)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

colv is a vector to be filled with the names of the key columns of the table.
Names of descending key columns are preceded with a minus sign (-).


ΓòÉΓòÉΓòÉ 190.2.4. NOKEYS() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇNOKEYS()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Makes the object into an unKEYED table.


ΓòÉΓòÉΓòÉ 190.2.5. SETKEYS() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSETKEYS(colv)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

colv is a vector containing the names of columns which are to become the keys
of the table. SETKEYS() makes the object into a keyed table, and thus affects
the KEYED attribute.


ΓòÉΓòÉΓòÉ 190.2.6. SAVETO() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSAVETO(filename)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

 Saves the TABLE data as a new OS/2 file.


ΓòÉΓòÉΓòÉ 190.3. Examples ΓòÉΓòÉΓòÉ

This procedure provides code which demonstrates the use of a TABLE object.

/*----------------------------------------------------------------------*/
/* Define a new table of four columns. Specify two key columns and add  */
/* four rows of data.                                                   */
/*----------------------------------------------------------------------*/
PROCEDURE TABLE
DO
  DECLARE NUMERIC i
  DECLARE NUMERIC j
  OPEN SYSTEM Sys                    ! This is often useful

  ! First erase the old table if necessary, FORGIVE in case it
  ! isn't there). Then open the table.
  FORGIVE CALL Sys'DELETE("D:\Address.tab")
  OPEN TABLE AddTab,                 ! Handle of table
   NAME = "Address.tab",             ! Name of address table
   LOCATION = "D:\",                 ! Location of address table
   MODE = "WRITE"                    ! Need write access to the table

  ! Now define the columns (the order does not matter)
  DEFINE AddTab.Name[0]
  DEFINE AddTab.Address[0]
  DEFINE AddTab.Phone[0]
  DEFINE AddTab.CustomerNo[0]

  ! Set the column types (although this isn't essential)
  LET AddTab.Name      [0]'TYPE = "Character"
  LET AddTab.Address   [0]'TYPE = "Character"
  LET AddTab.Phone     [0]'TYPE = "Numeric"
  LET AddTab.CustomerNo[0]'TYPE = "Numeric"

  ! Now set the key columns up. This could also be done after the
  ! data has been inserted IF each column is treated separately
  ! and the data is inserted in the correct key order. (It is
  ! actually quicker for bulk data to insert the data into the
  ! table before keying the table, provided the data is inserted
  ! in the right order and all the columns are the same length
  ! when the SETKEYS action is performed.)
  DEFINE Keys[0]                     ! Vector for key column names
  INSERT Keys[0] = "CustomerNo"      ! First entry is the first key
  INSERT Keys[0] = "Name"            ! Second entry is the second key
  ! Use a minus sign to specify a descending key
  !(for example, LET Keys[2] = "-Name")
  CALL AddTab'SETKEYS(Keys)          ! Pass the key names to the table
  LET AddTab.CustomerNo[0]'ORDER = 1 ! Set column order
  LET AddTab.Name      [0]'ORDER = 2
  LET AddTab.Phone     [0]'ORDER = 3
  LET AddTab.Address   [0]'ORDER = 4

  ! Now we can insert the data.
  ! Create a new row using INSERT or INSERT().
  INSERT AddTab.CustomerNo{10002, "Henry Einsiedler"}
  row = INSERT(AddTab.CustomerNo{10007, "William Slocombe"})

  ! We can assign a column value when we insert the row.
  INSERT AddTab.Phone{10004, "Huw Owen"} = 293845
  row = INSERT(AddTab.Phone{10006, "Sally Cohen"}, 205774)

  ! For the rest of the column values, identify the row by its key.
  LET AddTab.Address{10002, "Henry Einsiedler"} =
   "28 Priorsfield Road, Handforth"
  LET AddTab.Phone{10002, "Henry Einsiedler"} = 69884
  LET AddTab.Address{10004, "Huw Owen"} =
   "28 London Road, Helston"

  ! If we know the row number, we can identify the row directly. The
  ! row number is only valid if there have been no further INSERTs.
  LET AddTab.Address[row] = "The Manor, Long Compton"

  ! We can get the row number for a given key using the ROW function.
  row = ROW(AddTab.CustomerNo{10007, "William Slocombe"} )
  LET AddTab.Address[row] = "71 Hunts Road, Ayr"
  LET AddTab.Phone  [row] = 42597
start program s,'showtab', start(pointer(addtab[0]))

  ! Another column can be added at any time - use DEFINE x[*]
  ! to specify the same number of rows as the rest of the table.
  ! Delete a row by deleting any of the column entries for that row
  ! for example,  DELETE AddTab.Code{10002, "Henry Einsiedler"}
  DEFINE AddTab.Code[*]
  LET AddTab.Code{10004, "Huw Owen"} = 99
start program s,'showtab', start(pointer(addtab[0]))

  ! Now suppose it is necessary to change the keys of the table.
  ! SETKEYS can be used again - but only when the data is in the
  ! new order. The INDEX function must be used to find the new
  ! order for the table and the rows must be sorted.
  ! First find out the new order for the rows - Take the Address
  ! column as key 1 and phone as a descending key 2. Rowindex is
  ! a vector of row numbers in the new order
  INDEX rowindex = -AddTab.Phone, AddTab.Address

  ! Next open a new table to hold the sorted rows of data.
  ! First erase the old table if necessary
  FORGIVE CALL Sys'DELETE("D:\Address.TMP")
  OPEN TABLE NewTab,                 ! Handle of table
   NAME = "Address.TMP",             ! Name of new table
   LOCATION = "D:\",                 ! Location of new table
   MODE = "WRITE"                    ! Need write access to the table

  ! Define the same columns in the temporary table. We can find
  ! out what the old columns are using the COLUMNS attribute and
  ! COLUMNS action, and the number of rows with the ROWS attribute
  numcols = AddTab'COLUMNS           ! Number of columns in table
  CALL AddTab'COLUMNS(addcols)       ! Get vector of column names
  numrows = AddTab'ROWS              ! Number of rows in table

  ! Now do the actual work. Make a pointer to the old and new
  ! columns (don't have to use a pointer but its faster if we do),
  ! define the new column, copy across the data type and all the
  ! data in the order prescribed by the rowindex vector from above.
  DO i = 1 : numcols                 ! For each column . . .
    ! Construct pointer to new and old columns
    newcol = POINTER("NewTab."~addcols[i])
    oldcol = POINTER("AddTab."~addcols[i])

    ! Define the new column and copy the column type across
    DEFINE (?newcol)[0]
    (?newcol)[0]'TYPE = (?oldcol)[0]'TYPE

    ! Now copy the columns data across in the correct order
    DO j = 1 : numrows               ! For each row . . .
      INSERT (?newcol)[0] =          ! Insert as the last element
       (?oldcol)[ rowindex[j] ]      !   the j'th ordered element
    END
  END

  ! Now key the new table using setkeys.
  DEFINE Keys[0]
  INSERT Keys[0] = "-Phone"          ! 1st key Phone   (descending)
  INSERT Keys[0] = "Address"         ! 2nd key Address (ascending)
  CALL NewTab'SETKEYS(Keys)
  LET NewTab.Phone     [0]'ORDER = 1 ! Set column order
  LET NewTab.Address   [0]'ORDER = 2
  LET NewTab.CustomerNo[0]'ORDER = 3
  LET NewTab.Name      [0]'ORDER = 4
  LET NewTab.Code      [0]'ORDER = 5
start program s,'showtab', start(pointer(newtab[0]))

  ! If this all worked we can discard the original by setting KEEP
  addtab'keep = 0                    ! Don't want to keep the table
  SHUT AddTab

  ! If the table is to be used in Visualizer (for example, Table or
  ! Chart), it is necessary to set the OBJECTCLASS attribute of the table
  LET NewTab'OBJECTCLASS = "IBMTABLE"

  ! Now SHUT the temporary table and rename it
  SHUT NewTab
  CALL Sys'RENAME("D:\Address.TMP", "D:\Address.tab")

  SHUT sys
END

The following example writes the contents of a table to a flat comma-separated
file.

/*----------------------------------------------------*/
/* Print a table as a comma-separated file            */
/* For example, CALL CSV( 'EMPDATA', 'EMPDATA.PRT' )  */
/*----------------------------------------------------*/
PROCEDURE CSV( tablename, filename )
DO
  DECLARE CHAR[*] tablename   ! Table name, anywhere on FTB1PATH
  DECLARE CHAR[*] filename    ! Output file, in FTB1DIR

  DECLARE NUMERIC r
  DECLARE NUMERIC c
  DECLARE CHAR[*] cell
  DECLARE DEFINED TASK POINTER pcols
  OPEN SYSTEM  sys
  OPEN PROFILE prf

  ! Open the output file
  OPEN FILE PrtFile,
   NAME = filename,
   LOCATION = prf'FTB1DIR,
   MODE = 'WRITE'

  ! Open the input table
  OPEN TABLE MyTab,
   NAME = tablename,
   LOCATION = sys'SEARCHPATH( tablename ),
   MODE='READ'

  !Get a list of the column names and create pointers to them
  CALL MyTab'COLUMNS(cols)
  DEFINE pcols[ cols[0]'ENTRIES ]
  DO c = 1 : cols[0]'ENTRIES
    LET pcols[ c ] = POINTER( 'MyTab.'||cols[ c ] )
  END

  !Loop through the rows of the table
  LET txt=''
  DO r = 1 : MyTab'ROWS
    ! Loop through the columns of the row
    DO c = 1 : pcols[0]'ENTRIES
      ! Add the contents of the cell and a comma
      LET cell = (?(pcols[c]))[r]
      LET txt ||= STRING( IF(SCAN(cell,','),'^,','_,'), cell )
    END
    ! Write record to file and prepare for the next line
    CALL PrtFile'put(txt,line())
    LET txt = ''
  END
  SHUT PrtFile
  SHUT MyTab
  CLEAR pcols
END

A sample result file from a table is shown below:

100871,'Bacchus, Judy',420,Head Office,F,70,$18424.18,$0.00,2,M,61/8/17,...
102082,'Love, George',632,Research,M,50,$55272.54,$0.00,3,M,51/6/7,...
103129,'Acevedo, Charlie',632,Research,M,50,$65193.24,$0.00,3,M,55/11/16,...
103624,'Kaiser, Steve',140,Production,M,31,$12400.88,$0.00,1,S,71/6/13,...

Examples source library:


ΓòÉΓòÉΓòÉ 191. TAN(), TAND() ΓòÉΓòÉΓòÉ

The TAN() and TAND() functions return the tangent of an angle.

TAN() returns the tangent for an angle specified in radians. TAND() returns the
tangent for an angle specified in degrees.

ΓöÇΓöÇTAN(angle)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

ΓöÇΓöÇTAND(angle)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Examples

More about TAN() and TAND()


ΓòÉΓòÉΓòÉ 191.1. Examples ΓòÉΓòÉΓòÉ

x = TAN(1)                                  !  Result is 1.56
x = TAND(58.93)                             !  Result is 1.66

Examples source library:


ΓòÉΓòÉΓòÉ 191.2. More about TAN() and TAND() ΓòÉΓòÉΓòÉ

o Where the result of TAN() or TAND() equals infinity, the system upper limit
  value is returned.  An error is not generated automatically.


ΓòÉΓòÉΓòÉ 192. TARGETCTRL ΓòÉΓòÉΓòÉ

This object defines the direct manipulation capabilities of an application as a
target for a drop. It may be associated with a window to enable the window to
be the target for a drop.

Attributes

Actions

Events

Examples

See also: SOURCECTRL, REFERENCE, DDECLIENT, STREAM


ΓòÉΓòÉΓòÉ 192.1. Attributes ΓòÉΓòÉΓòÉ

CODE                     CONTAINERNAME
OPERATION                ORIGINATOR
SOURCENAME               TRACE


ΓòÉΓòÉΓòÉ 192.1.1. CODE ΓòÉΓòÉΓòÉ

This attribute may be queried to obtain the error code of the last TARGETCTRL
operation.


ΓòÉΓòÉΓòÉ 192.1.2. CONTAINERNAME ΓòÉΓòÉΓòÉ

This read-only attribute identifies the source container name. It returns a
character string of up to 255 bytes. If the source object is a file, the
attribute will contain the drive and directory.


ΓòÉΓòÉΓòÉ 192.1.3. OPERATION ΓòÉΓòÉΓòÉ

Identifies the drag/drop operation: M, C, or L for move, copy or link.

Read-only


ΓòÉΓòÉΓòÉ 192.1.4. ORIGINATOR ΓòÉΓòÉΓòÉ

This read-only attribute identifies the screen object that was dropped on.


ΓòÉΓòÉΓòÉ 192.1.5. SOURCENAME ΓòÉΓòÉΓòÉ

This read-only attribute identifies the source object name. It returns a
character string of up to 255 bytes. If the source object is a file, the
attribute will contain the fine name.


ΓòÉΓòÉΓòÉ 192.1.6. TRACE ΓòÉΓòÉΓòÉ

This Boolean attribute controls whether trace information will be recorded.

Drag/Drop trace will be written to the FTBDRG file in the FTB1DIR directory.

Default: 0 (No tracing, set on OPEN then read-only)


ΓòÉΓòÉΓòÉ 192.2. Actions ΓòÉΓòÉΓòÉ

ADDFORMAT()             ADDTYPE()
ADDFMTEXT()             ADDTYPEEXT()
FORMATS()               TYPES()
FMTEXTS()               TYPEEXTS()


ΓòÉΓòÉΓòÉ 192.2.1. ADDFORMAT() ΓòÉΓòÉΓòÉ

                      ΓöîΓöÇ"CML"ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ   ΓöîΓöÇ0ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöÇΓöÇADDFORMAT(format,ΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇ,ΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                      ΓööΓöÇoperationsΓöÇΓöÿ   ΓööΓöÇreferenceΓöÇΓöÿ

This action may be used to signify that a target data format is supported.

format is provided by the caller, and should be a character string representing
a data format name, such as: DIF, IXF, DBF, IBMCHART.

operations is optionally provided by the caller, and is used to define the
operations that are valid for the specified format. It should be a character
string including one instance of one or more of the following characters:

M         Move
C         Copy
L         Link

The order of these characters is relevant in that the first character in the
string is taken as the default operation. If omitted, operations defaults to
"CML", or "CL" if the specified format does not match the native format of the
source. Even if specified, move will not be allowed unless the format matches
the native format of the source.

If any other character is specified, an error condition will result.

When a drop occurs, then the FORMAT attribute of the STREAM delivered with the
TARGET event reflects the format match that allowed the drop. If it was a Link
operation, then the LINK and REFERENCE attributes of the STREAM are set to 1
(true). Use a LINK object to process the data.

reference is optionally provided by the caller. It is used to define whether a
reference to data is required or the data itself. It must be a Boolean value.
The default is 0 (false).

For example, a file containing data of a given format can be dropped on the
application. If reference is 1 (true), then a reference to the data is
delivered to the TARGET event. If reference is 0 (false), then the data itself
is delivered.

When a drop occurs, then the FORMAT attribute of the STREAM delivered with the
TARGET event reflects the format match that allowed the drop to occur. When a
reference is delivered, then the REFERENCE attribute of the STREAM object is
set to 1 (true). Use a REFERENCE object to interpret the data.

Repeated ADDFORMAT requests are cumulative. You can use them to build up a set
of supported target formats and operations. If multiple ADDFORMAT requests are
issued for the same format, then the last one takes precedence.

The order of ADDFORMAT requests indicates the sequence of preferred formats.
The first is most favored.


ΓòÉΓòÉΓòÉ 192.2.2. ADDTYPE() ΓòÉΓòÉΓòÉ

                  ΓöîΓöÇ"CML"ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöÇΓöÇADDTYPE(type,ΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                  ΓööΓöÇoperationsΓöÇΓöÿ

This action may be used to signify that a target type is supported.

type is provided by the caller, and should be a character string representing a
source type that is acceptable. If the source represents an OS/2 file, the type
will be (one of) the value(s) in the .TYPE extended attribute.

operations is optionally provided by the caller, and is used to define the
operations that are valid for the specified format. It is a character string
including one instance of one or more of:

M         Move
C         Copy
L         Link

If any other character is specified, then an error condition results.

The first character in the string specifies the default operation.

Repeated ADDTYPE requests are cumulative, and may be used to build up a set of
supported types. If multiple ADDTYPE requests are issued for the same type, the
last one takes precedence.

The order of ADDTYPE requests is not important.


ΓòÉΓòÉΓòÉ 192.2.3. ADDFMTEXT() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇADDFMTEXT(Format,Extension)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action may be used to equate a format to a file extension.

Format is provided by the caller, and should obey the same rules as the
equivalent parameter on the ADDFORMAT action.

Extension is provided by the caller, and should be a character string
indicating the file extension to be equated with the specified format.
Extension can be of any length since the comparison is made based on the last
period. Provided the format has been defined as acceptable, files with the
specified extension may be dropped. If the format has not been defined, no
error occurs, but files with the specified extension may not be dropped.

Repeated ADDFMTEXT requests are cumulative, and may be used to build up a set
of format to file extension mappings. If multiple ADDFMTEXT requests are issued
for the same file extension, the last one takes precedence.


ΓòÉΓòÉΓòÉ 192.2.4. ADDTYPEEXT() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇADDTYPEEXT(Type,Extension)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action may be used to equate a type to a file extension.

Type and should obey the same rules as the equivalent parameter on the ADDTYPE
action.

Extension should be a character string indicating the file extension to be
equated with the specified format. Extension can be of any length since the
comparison is made based on the last period found. Provided the format has been
defined as acceptable, files with the specified extension may be dropped. If
the format has not been defined, no error occurs, but files with the specified
extension may not be dropped.

Repeated ADDTYPEEXT requests are cumulative, and may be used to build up a set
of type-to-file extension mappings. If multiple ADDTYPEEXT requests are issued
for the same file extension, the last one takes precedence.


ΓòÉΓòÉΓòÉ 192.2.5. FORMATS() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇFORMATS(formats,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                     ΓööΓöÇoperationsΓöÇΓöÿ   ΓööΓöÇreferenceΓöÇΓöÿ

This action may be used to define a complete set of supported target formats
and operations.

formats is the name of a scalar or vector containing data format names. Each
value should conform to the rules defined for the format parameter on the
ADDFORMAT action.

operations is optional and is the name of a scalar or vector containing the
valid operations for each format. Each value should conform to the rules
defined for the operations parameter on the ADDFORMAT action, with the
additional possibility of being NULL to indicate that the default set of
operations should be assumed for the corresponding format.

reference is optionally provided by the caller, and is the name of a scalar or
vector containing the Boolean reference flags for each format. Each value
should conform to the rules defined for the reference parameter on the
ADDFORMAT action (with the additional possibility of being NULL to indicate
that the default value should be assumed for the corresponding format).

If the formats vector has more elements than the operations vector, the excess
formats will assume the default operations. If the operations vector has more
elements than the formats vector, the excess will be ignored.

The FORMATS action will replace any prior definition of supported target
formats and operations.

The order of formats in the formats vector is relevant, and indicates the
sequence of preferred formats, first being most favored.


ΓòÉΓòÉΓòÉ 192.2.6. TYPES() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇTYPES(Types,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                 ΓööΓöÇOperationsΓöÇΓöÿ

This action may be used to define a complete set of supported target types and
operations.

Types is the name of a scalar or vector containing type names. Each value
should conform to the rules defined for the Type parameter on the ADDTYPE
action.

Operations is optional, and is the name of a scalar or vector containing the
valid operations for each type. Each value should conform to the rules defined
for the Operations parameter on the ADDTYPE action, with the additional
possibility of being NULL to indicate that the default set of operations should
be assumed for the corresponding format.

If the types vector has more elements than the operations vector, the excess
types will assume the default operations. If the operations vector has more
elements than the types vector, the excess will be ignored.

The TYPES action will replace any prior definition of supported target types
and operations.

The order of types in the Types vector is not important.


ΓòÉΓòÉΓòÉ 192.2.7. FMTEXTS() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇFMTEXTS(Formats,Extensions)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action may be used to define a complete set of format to file extension
mappings.

Formats is provided by the caller, and should obey the same rules as the
equivalent parameter on the FORMATS action.

Extensions is provided by the caller, and is the name of a scalar or vector
containing file extensions. Each value should conform to the rules defined for
the Extension parameter on the ADDFMTEXTS action.

If the formats vector and extensions vector do not have the same number of
elements, the excess will be ignored.

The FMTEXTS action will replace any prior definition of format to file
extension mapping.


ΓòÉΓòÉΓòÉ 192.2.8. TYPEEXTS() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇTYPEEXTS(Types,Extensions)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

This action may be used to define a complete set of type to file extension
mappings.

Types is provided by the caller, and should obey the same rules as the
equivalent parameter on the TYPES action.

Extensions is provided by the caller, and is the name of a scalar or vector
containing file extensions. Each value should conform to the rules defined for
the Extension parameter on the ADDFMTEXTS action.

If the types vector and extensions vector do not have the same number of
elements, the excess will be ignored.

The TYPEEXTS action will replace any prior definition of type to file extension
mapping.


ΓòÉΓòÉΓòÉ 192.3. Events ΓòÉΓòÉΓòÉ

TARGET(pStream)


ΓòÉΓòÉΓòÉ 192.3.1. TARGET(pStream) ΓòÉΓòÉΓòÉ

Signaled when a valid drop occurs.

pStream is a pointer to a STREAM object delivered with the event, through which
the data may be extracted. The ORIGINATOR attribute of the STREAM object passed
with the SOURCE event identifies the TARGETCTRL object through which the event
was generated. The ORIGIN attribute of the TARGETCTRL object will identify the
screen object that was dropped on. The FORMAT attribute of the STREAM object
may be used to identify the data format being delivered.

If a reference to the data is being delivered, then the REFERENCE attribute of
the STREAM object is 1 (true). Use a REFERENCE object to interpret the
information.

Once data has been extracted from the STREAM object, its FINISHED() action
should be called. If any errors are encountered in the data, for instance if
the data does not conform to the expected format, the STATUS attribute should
be set to a positive nonzero integer prior to calling the FINISHED() action.


ΓòÉΓòÉΓòÉ 192.4. Examples ΓòÉΓòÉΓòÉ

See DRAGDROP.PRG in the dataechg examples in Development Samples for more
information.

Examples source library:


ΓòÉΓòÉΓòÉ 193. TBAR ΓòÉΓòÉΓòÉ

The TBAR object class provides an instance of a tool bar.

Parent: WINDOW

Attributes

Actions

Events

More about TBAR

Examples

See also: WINDOW, PUSH.


ΓòÉΓòÉΓòÉ 193.1. Attributes ΓòÉΓòÉΓòÉ

UP                    DOWN
DISABLED              LATCH
INISTATE              GROUP
TOGGLE                TOOLDATA
TOOLTEXT              HELP
HELPIDS               HELPGLOBAL
SIZEY                 VISIBLE


ΓòÉΓòÉΓòÉ 193.1.1. UP ΓòÉΓòÉΓòÉ

Pointer to an array of bitmap names for the up state buttons.


ΓòÉΓòÉΓòÉ 193.1.2. DOWN ΓòÉΓòÉΓòÉ

Pointer to an array of bitmap names for the down state buttons.


ΓòÉΓòÉΓòÉ 193.1.3. DISABLED ΓòÉΓòÉΓòÉ

Pointer to an array of bitmap names for the disabled state buttons.


ΓòÉΓòÉΓòÉ 193.1.4. LATCH ΓòÉΓòÉΓòÉ

Pointer to an array that specifies whether each button latches when pressed or
pops back up. Each entry in the array is either 0 (pop back up), or 1 (latch).


ΓòÉΓòÉΓòÉ 193.1.5. INISTATE ΓòÉΓòÉΓòÉ

Pointer to an array that specifies the initial state of each button. Each entry
in the array is either "UP", "DOWN", or "DISABLED".


ΓòÉΓòÉΓòÉ 193.1.6. GROUP ΓòÉΓòÉΓòÉ

Pointer to an array that groups the buttons on the tool bar. Each entry in the
array is a number that specifies the gap between the button and the previous
one:

0         No gap (between buttons that toggle each other)
1         Small gap (between buttons in a group)
2         Large gap (between groups of buttons)


ΓòÉΓòÉΓòÉ 193.1.7. TOGGLE ΓòÉΓòÉΓòÉ

Pointer to an array that specifies whether each button toggles other buttons.
Each entry in the array is a number. Tool bar buttons that have the number zero
do not toggle any other buttons. Tool bar buttons that have the same nonzero
TOGGLE number toggle each other.


ΓòÉΓòÉΓòÉ 193.1.8. TOOLDATA ΓòÉΓòÉΓòÉ

Pointer to an array of object names. The object names are used when tool bar
events are raised.


ΓòÉΓòÉΓòÉ 193.1.9. TOOLTEXT ΓòÉΓòÉΓòÉ

Pointer to an array that specifies the text strings displayed when the user
presses mouse button 2 on each tool bar button.


ΓòÉΓòÉΓòÉ 193.1.10. HELP ΓòÉΓòÉΓòÉ

Pointer to an open HELP object.


ΓòÉΓòÉΓòÉ 193.1.11. HELPIDS ΓòÉΓòÉΓòÉ

Pointer to an array of help IDs for the tool bar buttons.


ΓòÉΓòÉΓòÉ 193.1.12. HELPGLOBAL ΓòÉΓòÉΓòÉ

The help ID of the global help text for the tool bar.


ΓòÉΓòÉΓòÉ 193.1.13. SIZEY ΓòÉΓòÉΓòÉ

The y-size of the tool bar. Read-only.


ΓòÉΓòÉΓòÉ 193.1.14. VISIBLE ΓòÉΓòÉΓòÉ

Whether the tool bar is visible: either 1 (visible), or 0 (hidden). Default: 1
(visible).


ΓòÉΓòÉΓòÉ 193.2. Actions ΓòÉΓòÉΓòÉ

STATE()             FILTER()


ΓòÉΓòÉΓòÉ 193.2.1. STATE() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSTATE(object,state)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Sets the new state of a button.

object    Object name of the button as specified in the TOOLDATA array.
state     New state: either "UP", "DOWN", or "DISABLED".


ΓòÉΓòÉΓòÉ 193.2.2. FILTER() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇFILTER(A.System.Event,A.System.Object,A.System.Boxnumber)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Filters tool bar selections, mouse button 2 selections, and removal of
description text.

If a tool bar button was selected, then FILTER() returns the object name of the
button as specified in the TOOLDATA array. Otherwise it returns A.System.Object
unchanged.


ΓòÉΓòÉΓòÉ 193.3. Events ΓòÉΓòÉΓòÉ

SELECT                PROPERTIES


ΓòÉΓòÉΓòÉ 193.3.1. SELECT ΓòÉΓòÉΓòÉ

Signaled when the user selects a tool bar button.

The returned value of A.System.Object from the FILTER() action is the object
name of the button as specified in the TOOLDATA array.


ΓòÉΓòÉΓòÉ 193.3.2. PROPERTIES ΓòÉΓòÉΓòÉ

Signaled when the user presses mouse button 2 on a tool bar button.

To display the tool bar button description as specified in the TOOLTEXT array,
an ON PROPERTIES block must be present, and it must call the FILTER() action.


ΓòÉΓòÉΓòÉ 193.4. More about TBAR ΓòÉΓòÉΓòÉ

o On OPEN, set all of the attributes that specify pointers to arrays. The
  arrays must all be the same size. The size of the arrays determines the
  number of tool bar buttons displayed. The elements of the arrays specify the
  properties of each button.

o For the UP, DOWN, and DISABLED attributes, each bitmap name is either the
  fully qualified name of an icon file, or a string in the form dllname<id>,
  where dllname is the name of a DLL and id is the resource ID of the icon
  within that DLL.

o Call the FILTER() action first in every event block in your program.

    LET A.System.Object = MyToolBar'FILTER(
                            A.System.Event,
                            A.System.Object,
                            A.System.BoxNumber)

o When a tool bar is visible on a window, the remaining usable area of the
  window is the SIZEY of the WINDOW minus the SIZEY of the TBAR.

o When the user presses F1 with a tool bar context menu displayed, then the
  help ID for the corresponding tool bar button is used to display help. This
  help ID is specified by HELPIDS.

  When the user selects Help from a tool bar context menu, then the global help
  ID is used to display help. This help ID is specified by HELPGLOBAL.


ΓòÉΓòÉΓòÉ 193.5. Examples ΓòÉΓòÉΓòÉ

ON START
DO
  OPEN HELP MyHelp

  OPEN WINDOW MyWin,, "I.WINDOWS.MyWindow",   ! open a saved window
   VISIBLE = 0

  ! Now we prepare the toolbar information arrays

  DEFINE tbarUp[0]      /* array of UP bitmaps          */
  DEFINE tbarDown[0]    /* array of DOWN bitmaps        */
  DEFINE tbarDis[0]     /* array of DISABLED bitmaps    */

  DEFINE tbarLatch[0]   /* array of latchable values    */
  DEFINE tbarGroup[0]   /* array of button groupings    */
  DEFINE tbarToggle[0]  /* array of toggle groupings    */
  DEFINE tbarInit[0]    /* array of initial states      */

  DEFINE tbarNames[0]   /* array of button object names */
  DEFINE tbarDesc[0]    /* array of description texts   */
  DEFINE tbarHelp[0]    /* array of help text res IDs   */

  ! The UP bitmaps. Notice that bitmaps can be identified by
  ! fully-qualified file name, or by DLL name and resource ID
  INSERT tbarUp[0]     = "d:\ftc\ftdup.bmp"
  INSERT tbarUp[0]     = "d:\mybmps\u_smiley.bmp"
  INSERT tbarUp[0]     = "FTBBMPS<1010>"
  INSERT tbarUp[0]     = "MYBMPDLL<1>"

  ! The DOWN bitmaps.
  INSERT tbarDown[0]   = "d:\ftc\ftddwn.bmp"
  INSERT tbarDown[0]   = "d:\mybmps\d_smiley.bmp"
  INSERT tbarDown[0]   = "FTBBMPS<1001>"
  INSERT tbarDown[0]   = "MYBMPDLL<2>"

  ! The DISABLED bitmaps.
  INSERT tbarDis[0]    = "d:\ftc\ftddis.bmp"
  INSERT tbarDis[0]    = "d:\mybmps\x_smiley.bmp"
  INSERT tbarDis[0]    = "FTBBMPS<1002>"
  INSERT tbarDis[0]    = "MYBMPDLL<3>"

  ! Our third and fourth buttons are to be latchable
  INSERT tbarLatch[0]  = 0
  INSERT tbarLatch[0]  = 0
  INSERT tbarLatch[0]  = 1
  INSERT tbarLatch[0]  = 1

  ! Keep the first one separate, and group the other three together
  INSERT tbarGroup[0]  = 0
  INSERT tbarGroup[0]  = 2   /* large gap between first and second
  INSERT tbarGroup[0]  = 1   /* small gap between second and third
  INSERT tbarGroup[0]  = 0   /* no gap between the two that toggle

  ! Our second two buttons will toggle each other on and off
  ! All the '1's form a toggle group, and the '2's, and so on
  ! This only makes sense for latchable buttons
  INSERT tbarToggle[0] = 0   /* 0 = no toggling */
  INSERT tbarToggle[0] = 0
  INSERT tbarToggle[0] = 1
  INSERT tbarToggle[0] = 1

  ! Initial states - all up, except button four which will be down
  INSERT tbarInit[0]   = "UP"
  INSERT tbarInit[0]   = "UP"
  INSERT tbarInit[0]   = "UP"
  INSERT tbarInit[0]   = "DOWN"

  ! Object names - we can choose these as we like
  INSERT tbarNames[0]  = "T.MyToolBar.Blank"
  INSERT tbarNames[0]  = "T.MyToolBar.Smile"
  INSERT tbarNames[0]  = "T.MyToolBar.Compile"
  INSERT tbarNames[0]  = "T.MyToolBar.Special"

  ! Button description texts
  INSERT tbarDesc[0]   = "Nothing"
  INSERT tbarDesc[0]   = "Smile please!"
  INSERT tbarDesc[0]   = "Select a table or query..."
  INSERT tbarDesc[0]   = "Configure options"

  ! Button help text res IDs
  INSERT tbarHelp[0]   = 10192
  INSERT tbarHelp[0]   = 10193
  INSERT tbarHelp[0]   = 10194
  INSERT tbarHelp[0]   = 10195

  ! Now open the tool bar

  OPEN TBAR MyToolBar, MyWin,     /* open tool bar on my window */
   UP         = POINTER(tbarUp[0]),
   DOWN       = POINTER(tbarDown[0]),
   DISABLED   = POINTER(tbarDis[0]),
   LATCH      = POINTER(tbarLatch[0]),
   GROUP      = POINTER(tbarGroup[0]),
   TOGGLE     = POINTER(tbarToggle[0]),
   INISTATE   = POINTER(tbarInit[0]),
   TOOLDATA   = POINTER(tbarNames[0]),
   TOOLTEXT   = POINTER(tbarDesc[0]),
   HELPIDS    = POINTER(tbarHelp[0]),
   HELP       = POINTER(MyHelp[0]),
   HELPGLOBAL = 10191,
   VISIBLE    = 1

  LET MyWin'VISIBLE = 1
END

ON DESKTOP
DO
  LET A.System.Object = MyToolBar'FILTER(
                         A.System.Event,
                         A.System.Object,
                         A.System.BoxNumber)
    ...

ON SELECT
DO
  LET A.System.Object = MyToolBar'FILTER(
                         A.System.Event,
                         A.System.Object,
                         A.System.BoxNumber)

  CASE A.System.Object
    WHEN "T.MyToolBar.Nothing"
      NOTHING

    WHEN "T.MyToolBar.Smile"
      CALL do_smile(42)

    ...

ON PROPERTIES    /* signaled when the user uses the right */
DO               /* mouse button on a tool bar button     */
  CALL MyToolBar'FILTER(
        A.System.Event,
        A.System.Object,
        A.System.BoxNumber)
END

Examples source library:


ΓòÉΓòÉΓòÉ 194. TERMINATE ΓòÉΓòÉΓòÉ

The TERMINATE statement halts the processing of a specified repeating block.

ΓöÇΓöÇTERMINATEΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
               ΓööΓöÇnumberΓöÇΓöÿ

Examples

More about TERMINATE

See also: ITERATE, LEAVE


ΓòÉΓòÉΓòÉ 194.1. Examples ΓòÉΓòÉΓòÉ

DEFINE Array[5,10]
Valid = 0
DO Row = 1:5
  DO Cell = 1:10
    IF NULL(Array[Row,Cell])
    THEN TERMINATE 2         ! Halts at DO Row = 1:5
    Valid += 1
  END
END

Examples source library:


ΓòÉΓòÉΓòÉ 194.2. More about TERMINATE ΓòÉΓòÉΓòÉ

o TERMINATE can be used to stop the execution of a WHILE or UNTIL block, or a
  DO ... END block with parameters.


ΓòÉΓòÉΓòÉ 195. TEXT ΓòÉΓòÉΓòÉ

The TEXT object class creates an instance of a box containing a text string.

Parent: WINDOW

Attributes

Actions

Events

Examples

More about TEXT


ΓòÉΓòÉΓòÉ 195.1. Attributes ΓòÉΓòÉΓòÉ

CLONEDIR                CLONEGAP
CLONES                  BGCOLOR
ENABLED                 EXPRESSION
FGCOLOR                 HANDLES
HORZJUST                HELP
OL_ALL                  OL_COLOR
OL_DETAIL               OL_LEFT
OL_RIGHT                OL_OVER
OL_UNDER                ORIGIN
OVERFLOW                SELECTABLE
SIZEX                   SIZEY
TEXT                    VERTJUST
VISIBLE                 WORDWRAP
X                       Y


ΓòÉΓòÉΓòÉ 195.1.1. CLONEDIR ΓòÉΓòÉΓòÉ

Which way the clones are to be laid out relative to the original:

1         Down
2         Up
3         Left
4         Right

Set on OPEN, then read-only.

Default: 1 (Down)


ΓòÉΓòÉΓòÉ 195.1.2. CLONEGAP ΓòÉΓòÉΓòÉ

Space between clones, in dialog units.

Set on OPEN, then read-only.

Default: 0


ΓòÉΓòÉΓòÉ 195.1.3. CLONES ΓòÉΓòÉΓòÉ

Number of clones.

Default: 1


ΓòÉΓòÉΓòÉ 195.1.4. BGCOLOR ΓòÉΓòÉΓòÉ

Background color. Integer in the range 1-19. See Colors and color codes for
details of colors available.

Default: Defined by Presentation Manager.

If BGCOLOR for the window has been set, this color is passed to all controls on
the window as the default.


ΓòÉΓòÉΓòÉ 195.1.5. ENABLED ΓòÉΓòÉΓòÉ

Whether the text object is enabled:

0         Text object grayed out
1         Text object enabled

Default: 1 (Enabled)


ΓòÉΓòÉΓòÉ 195.1.6. EXPRESSION ΓòÉΓòÉΓòÉ

Pointer to a variable, the contents of which are displayed with the text box.

Note that the TEXT and EXPRESSION attributes are mutually exclusive.

Default: ""


ΓòÉΓòÉΓòÉ 195.1.7. FGCOLOR ΓòÉΓòÉΓòÉ

Foreground color. Integer in the range 1-19. See Colors and color codes for
details of colors available.

Default: Defined by Presentation Manager.


ΓòÉΓòÉΓòÉ 195.1.8. HANDLES ΓòÉΓòÉΓòÉ

Whether sizing handles are attached to the text control to support moving,
sizing, and copying operations. These direct manipulation techniques follow the
CUA guidelines. See also the AUTOSELECT attribute of the WINDOW object.

0         Handles are not displayed
1         Handles are displayed

Default: 0 (No handles)


ΓòÉΓòÉΓòÉ 195.1.9. HORZJUST ΓòÉΓòÉΓòÉ

Horizontal justification of the text in the entry box:

0         Left justified
1         Right justified
2         Centered

Default: 0 (Left justified)


ΓòÉΓòÉΓòÉ 195.1.10. HELP ΓòÉΓòÉΓòÉ

Resource identifier (res ID) of the full help text for this object.

Default: 0


ΓòÉΓòÉΓòÉ 195.1.11. OL_ALL ΓòÉΓòÉΓòÉ

Line style used around the text, cannot be queried.

0         Solid
2-6       Various dashed and dotted lines
7         Solid
8         Invisible

Default: 8 (Invisible)


ΓòÉΓòÉΓòÉ 195.1.12. OL_COLOR ΓòÉΓòÉΓòÉ

Outline color. Integer in the range 1-19. See Colors and color codes for
details of colors available.

Default: Defined by Presentation Manager


ΓòÉΓòÉΓòÉ 195.1.13. OL_DETAIL ΓòÉΓòÉΓòÉ

Line style used between rows of clones. Set on OPEN, then read-only.

0         Solid
2-6       Various dashed and dotted lines
7         Solid
8         Invisible

Default: 8 (Invisible)


ΓòÉΓòÉΓòÉ 195.1.14. OL_LEFT ΓòÉΓòÉΓòÉ

Line style used to the left of the box. Set on OPEN, then read-only.

0         Solid
2-6       Various dashed and dotted lines
7         Solid
8         Invisible

Default: 8 (Invisible)


ΓòÉΓòÉΓòÉ 195.1.15. OL_RIGHT ΓòÉΓòÉΓòÉ

Line style used to the right of the box. Set on OPEN, then read-only.

0         Solid
2-6       Various dashed and dotted lines
7         Solid
8         Invisible

Default: 8 (Invisible)


ΓòÉΓòÉΓòÉ 195.1.16. OL_OVER ΓòÉΓòÉΓòÉ

Line style used above the box. Set on OPEN, then read-only.

0         Solid
2-6       Various dashed and dotted lines
7         Solid
8         Invisible

Default: 8 (Invisible)


ΓòÉΓòÉΓòÉ 195.1.17. OL_UNDER ΓòÉΓòÉΓòÉ

Line style used below the box. Set on OPEN, then read-only.

0         Solid
2-6       Various dashed and dotted lines
7         Solid
8         Invisible

Default: 8 (Invisible)


ΓòÉΓòÉΓòÉ 195.1.18. ORIGIN ΓòÉΓòÉΓòÉ

The corner of the enclosing window to be taken as the origin. The position of
the text object is measured from this point.

"TL"      Top left
"TR"      Top right
"BL"      Bottom left
"BR"      Bottom right

Default: "BL" (Bottom left)


ΓòÉΓòÉΓòÉ 195.1.19. OVERFLOW ΓòÉΓòÉΓòÉ

Enables or disables numeric overflow indicator:

0         Overflow indicator off
1         Overflow indicator on

Default: 0 (Overflow indicator off)

This means that if the number being displayed is larger than the static text it
will be replaced by asterisks.  This is only used for numbers, and will not
work if wordwrap is on.


ΓòÉΓòÉΓòÉ 195.1.20. SELECTABLE ΓòÉΓòÉΓòÉ

If SELECTABLE is 1, clicking on the text once will cause an SELECT event, while
clicking twice will cause an OPEN event.

0         Not selectable (no SELECT or OPEN events)
1         Selectable

Default: 0


ΓòÉΓòÉΓòÉ 195.1.21. SIZEX ΓòÉΓòÉΓòÉ

Width, in dialog units.

Default: 0


ΓòÉΓòÉΓòÉ 195.1.22. SIZEY ΓòÉΓòÉΓòÉ

Height, in dialog units.

Default: 0


ΓòÉΓòÉΓòÉ 195.1.23. TEXT ΓòÉΓòÉΓòÉ

Text string to appear in the text box.

Note that the TEXT and EXPRESSION attributes are mutually exclusive.

Default: ""


ΓòÉΓòÉΓòÉ 195.1.24. VERTJUST ΓòÉΓòÉΓòÉ

Vertical justification of the text in the entry box:

0         Top justified
1         Bottom justified
2         Centered

Default: 0 (Top justified)


ΓòÉΓòÉΓòÉ 195.1.25. VISIBLE ΓòÉΓòÉΓòÉ

Whether the text object is displayed:

0         Text object not displayed
1         Text object displayed

Default: 1 (Displayed)


ΓòÉΓòÉΓòÉ 195.1.26. WORDWRAP ΓòÉΓòÉΓòÉ

Wraps the next word on to the following line when the length of the word
exceeds the space available on a line within the text box.

0         Wordwrap off
1         Wordwrap on

Default: 0 (Wordwrap off)


ΓòÉΓòÉΓòÉ 195.1.27. X ΓòÉΓòÉΓòÉ

Horizontal position within the window, in dialog units.

Default: 0


ΓòÉΓòÉΓòÉ 195.1.28. Y ΓòÉΓòÉΓòÉ

Vertical position within the window, in dialog units.

Default: 1


ΓòÉΓòÉΓòÉ 195.2. Actions ΓòÉΓòÉΓòÉ

EDIT()               REFRESH()


ΓòÉΓòÉΓòÉ 195.2.1. EDIT() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇEDIT(argument)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Enables the programmer to query whether a clipboard operation is supported and,
if it is, to carry it out.

argument is a clipboard query or a clipboard operation.

The following values for argument are used to check whether particular
clipboard operations can be supported with the text box in its current state:

"Querycut" Cut to clipboard
"Querycopy" Copy to clipboard
"Querypaste" Paste from clipboard
"Queryclear" Clear clipboard.

Where clipboard operations are supported, the following values for argument
direct them to be carried out:

"Cut"     Cut to clipboard
"Copy"    Copy to clipboard
"Paste"   Paste from clipboard
"Clear"   Clear clipboard.


ΓòÉΓòÉΓòÉ 195.2.2. REFRESH() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇREFRESH()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Forces repainting of the text box on screen.


ΓòÉΓòÉΓòÉ 195.3. Events ΓòÉΓòÉΓòÉ

DESKTOP            OPEN
SELECT


ΓòÉΓòÉΓòÉ 195.3.1. DESKTOP ΓòÉΓòÉΓòÉ

Signaled when the text control is moved, sized, or copied. A.System.Operation
is set to "MOVE", "SIZE", or "COPY". A.System.Object contains the name of the
control.


ΓòÉΓòÉΓòÉ 195.3.2. OPEN ΓòÉΓòÉΓòÉ

Mouse is clicked twice on text field.


ΓòÉΓòÉΓòÉ 195.3.3. SELECT ΓòÉΓòÉΓòÉ

Signaled when selection is made. A.System.Object is set to the text field name
and A.System.PositionX and A.System.PositionY are set to the coordinates of the
point selected. Coordinates are in world coordinate scale units.


ΓòÉΓòÉΓòÉ 195.4. Examples ΓòÉΓòÉΓòÉ

Sample code to open a TEXT object and create a cloned text box

OPEN TEXT text1, win,
 ORIGIN = "BL",
 X = 70, Y = 150,
 SIZEX = 80, SIZEY = 8,
 OL_ALL = 1,
 VISIBLE = 1,                     ! box is displayed (default)
 ENABLED = 1,
 TEXT = "simple text box",
 HORZJUST = 0,                    ! default left justified
 WORDWRAP = 0                     ! default, no wordwrap

DEFINE days[5] = "Friday"
OPEN text text2, win,
 X = 70, Y = 120,
 SIZEX = 50, SIZEY = 12,
 EXPRESSION = "days[1]",          ! display text in "days" array
 CLONES = 5,
 CLONEDIR = 1,
 CLONEGAP = 3,
 ORIGIN = "BL"

Examples source library:


ΓòÉΓòÉΓòÉ 195.5. More about TEXT ΓòÉΓòÉΓòÉ

o The following attributes can only be modified for the entire clone set, not
  for the individual clones:

   CLONEDIR
   CLONEGAP
   HANDLES


ΓòÉΓòÉΓòÉ 196. THEN ΓòÉΓòÉΓòÉ

The THEN statement introduces a statement or set of statements to be executed
when the associated IF condition is met.

The keyword THEN is optional.

ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇstatementlistΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
    ΓööΓöÇTHENΓöÇΓöÿ

Examples

More about THEN

See also: ELSE, IF ... THEN ... ELSE


ΓòÉΓòÉΓòÉ 196.1. Examples ΓòÉΓòÉΓòÉ

IF WORD( DATE(,'NdNmYYYY'), 1 ) = 'Fri' & TIME() > TIME('10:30')
THEN MESSAGE 'FTB0001',0,"Go home, it's the weekend"

Examples source library:


ΓòÉΓòÉΓòÉ 196.2. More about THEN ΓòÉΓòÉΓòÉ

o THEN can introduce a single statement or a set of statements. A set of
  statements must be enclosed in a DO ... END block.

o The single statement of a THEN clause, or the DO statement of a DO ... END
  block, can appear on the same line as the THEN, or on the following line.


ΓòÉΓòÉΓòÉ 197. TIME() ΓòÉΓòÉΓòÉ

The TIME() function converts a variable, a string, or a number to a time value.

ΓöÇΓöÇTIME(ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
          ΓööΓöÇexpressionΓöÇΓöÿ   ΓööΓöÇformatΓöÇΓöÿ

Examples

More about TIME()

See also: DATE(), PROFILE, RETYPE()

Also see Formatting data


ΓòÉΓòÉΓòÉ 197.1. Examples ΓòÉΓòÉΓòÉ

x   = TIME("10:25","HM")  ! Result is "10:25 A.M."
x   = TIME(1025,"HM")     ! Result is "10:25 A.M."
x   = TIME("10:25")       ! Result is "10:25 A.M."
now = TIME()              ! Sets now to current time

Examples source library:


ΓòÉΓòÉΓòÉ 197.2. More about TIME() ΓòÉΓòÉΓòÉ

o TIME() can be used to override the default time format used when data is
  converted implicitly by using LET to assign a value to a variable.

o The numbers 145, 0145, and the strings "145:", "0145" all indicate a time of
  1:45 AM.

o The string "14" is interpreted as the hour part of a time definition and
  indicates a time of 2:00 PM. To indicate a time of 0:14 AM, use the string
  "0014".


ΓòÉΓòÉΓòÉ 198. TIMER ΓòÉΓòÉΓòÉ

The TIMER object is available for scheduling activities at a particular date
and time or after a delay.

It is possible to open more than one timer object, but this is not necessary
since one TIMER object can generate multiple TIMER events.

Attributes: None.

Actions

Events

Examples

More about TIMER


ΓòÉΓòÉΓòÉ 198.1. Actions ΓòÉΓòÉΓòÉ

AT()               AFTER()


ΓòÉΓòÉΓòÉ 198.1.1. AT() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇAT(time,date,token)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

The AT() action causes a timer event at the specified time on the specified
date.

CALL mytimer'AT("17:30",, "EOWD")

date may be omitted and defaults to the current day.

token is an optional parameter to pass to the timer event.


ΓòÉΓòÉΓòÉ 198.1.2. AFTER() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇAFTER(seconds,token)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

The AFTER() action causes a timer event after the specified number of seconds
in the variable seconds. seconds can contain a fractional value (2.47 for
example).

CALL mytimer'AFTER( 60, "REMIND" )

token is an optional parameter to pass to the timer event.


ΓòÉΓòÉΓòÉ 198.2. Events ΓòÉΓòÉΓòÉ

TIMER


ΓòÉΓòÉΓòÉ 198.2.1. TIMER ΓòÉΓòÉΓòÉ

The TIMER object signals a TIMER event at the appropriate time. If the TIMER
object is closed, then all scheduled settings are lost. (Note that all objects
are closed when the application is closed).

A single optional parameter can be passed to the event block.


ΓòÉΓòÉΓòÉ 198.3. Examples ΓòÉΓòÉΓòÉ

OPEN TIMER mytimer
! End of working day warning at 5.30pm
CALL mytimer'AT( "17:30",, "EOWD")
! Reminder needed in 15mins
CALL mytimer'AFTER( 15*60, "REMIND")

The TIMER event can be processed by an ON TIMER event block. A single optional
parameter, named token in the examples, can be passed to the event block.

ON TIMER( token )
DO
  CASE token
    ! If event is the reminder then call the appropriate proc
    WHEN "REMIND"
      CALL REMINDER
    ! If the event is the end of day
    WHEN "EOWD"
      CALL GOHOME
  END
END

Examples source library:


ΓòÉΓòÉΓòÉ 198.4. More about TIMER ΓòÉΓòÉΓòÉ

o TIMER accuracy

  When a TIMER event occurs, it is made available as an asynchronous event with
  the same priority as other events such as the QUEUE statement. The ON TIMER
  block is executed when the event reaches the top of the queue. If the system
  is idle when this occurs, then the event is signaled immediately. However, if
  tasks are executing, then the TIMER event is delayed, and may occur at any
  point between or after other queued events.

o The TIMER will trigger the TIMER event at the appropriate time.  If the TIMER
  object is closed, all scheduled settings will be lost (note that all objects
  are closed when the application is closed).

o If the user is expected to enter a time you should be aware of TIMEFORMAT.
  Even though the workstation clock may show a 24 hour time format when you
  type TIME in a OS/2 session, Visualizer may display the time in a 12 hour
  time format (see Properties under Group on the Visualizer main window).

  For example, TIME in OS/2 may show 16:45, but Visualizer may show this time
  as 04:45, depending on the properties in the group window. A user may then
  type 04:55, expecting the timer to be activated in ten minutes, but it will
  in fact activate immediately. This is because Visualizer interprets this as
  04:55 in the morning, and that time is twelve hours earlier than the current
  time.

  You can avoid problems with differing time formats by setting the TIMEFORMAT
  attribute of the variable used to display the current time.  For example:

    LET timenow[0]'TIMEFORMAT = "hh:mm"

o The TIME() function can also be used to convert a time value according to an
  explicit format.


ΓòÉΓòÉΓòÉ 199. TOTAL() ΓòÉΓòÉΓòÉ

The TOTAL() function returns the sum of a series of values.

              <ΓöÇ,ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöÇΓöÇTOTALΓöÇΓöÇ(ΓöÇΓöÇΓöÇΓöÇexpressionΓöÇΓö┤ΓöÇΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Examples

More about TOTAL()


ΓòÉΓòÉΓòÉ 199.1. Examples ΓòÉΓòÉΓòÉ

x1 = 43
x2 = 9
x3 = 84
x4 = 44
Result = TOTAL(x1,x2,x3,x4)             ! Result is 180

DEFINE column[4]
column[1] = 1234
column[3] = 887
Result = TOTAL(column[0])               ! Result is 2121

Result = TOTAL(x1,x2,x3,x4,column[0])   ! Result is 2301

column[4] = "42"
Result = TOTAL(column[0])               ! Result is 2163

Examples source library:


ΓòÉΓòÉΓòÉ 199.2. More about TOTAL() ΓòÉΓòÉΓòÉ

o Any nonnumeric values are converted to numeric if possible. Nonnumeric values
  which cannot be converted are ignored.

o expression and subsequent expressions can reference individual values in an
  array.

o If any expression is NULL, then it is ignored.


ΓòÉΓòÉΓòÉ 200. TRACE ΓòÉΓòÉΓòÉ

The TRACE statement produces an execution time trace of statements as executed
during the Visualizer session. The trace is saved in S.System.Trace.

           ΓöîΓöÇOFFΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöÇΓöÇTRACEΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
           Γö£ΓöÇONΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
           Γö£ΓöÇLINEΓöÇΓöÇΓöÇΓöñ
           ΓööΓöÇBRANCHΓöÇΓöÿ

Examples

More about TRACE

See also: TRACE in User Library functions


ΓòÉΓòÉΓòÉ 200.1. Examples ΓòÉΓòÉΓòÉ

TRACE ON
CALL DodgyFunction(42)
TRACE OFF

Examples source library:


ΓòÉΓòÉΓòÉ 200.2. More about TRACE ΓòÉΓòÉΓòÉ

o TRACE without a parameter is interpreted as TRACE OFF.


ΓòÉΓòÉΓòÉ 201. TRIM() ΓòÉΓòÉΓòÉ

The TRIM() function returns a string trimmed of leading or trailing spaces.

                 ΓöîΓöÇ"B"ΓöÇΓöÇΓöÉ
ΓöÇΓöÇTRIM(string,ΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                 ΓööΓöÇtypeΓöÇΓöÿ

Examples

More about TRIM()

See also: CTRIM()


ΓòÉΓòÉΓòÉ 201.1. Examples ΓòÉΓòÉΓòÉ

x = TRIM(" asdf ")        ! Result is "asdf"
x = TRIM(" asdf ", "L" )  ! Result is "asdf "

Examples source library:


ΓòÉΓòÉΓòÉ 201.2. More about TRIM() ΓòÉΓòÉΓòÉ

o Using a string parameter of type NULL in this function produces a result of
  NULL.


ΓòÉΓòÉΓòÉ 202. TRUE ΓòÉΓòÉΓòÉ

The TRUE statement identifies a particular value of a CASE expression. When the
expression takes on a value which is nonzero, the statement following TRUE is
executed.

ΓöÇΓöÇTRUEΓöÇΓöÇstatementlistΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Examples

More about TRUE

See also: CASE...WHEN...OTHERWISE...END, FALSE, IF ... THEN ... ELSE, NULL


ΓòÉΓòÉΓòÉ 202.1. Examples ΓòÉΓòÉΓòÉ

X = 9
Y = 10
CASE X < Y
  TRUE
    MESSAGE "FTB0001",0,"2 - True ..."
  FALSE
    MESSAGE "FTB0001",0,"2 - False ..."
  NULL
    MESSAGE "FTB0001",0,"2 - Null ..."
  ! Note that "IF x < y ... ELSE DO ..." will run the THEN part
  ! when the expression is TRUE but not when the expression is NULL
  ! (which would arise if X or Y or both were NULL)
END

Examples source library:


ΓòÉΓòÉΓòÉ 202.2. More about TRUE ΓòÉΓòÉΓòÉ

o CASE...TRUE...FALSE...NULL...END performs a three-way test which takes
  account of NULL values.

  The IF statement performs a two-way test which is equivalent to
  CASE...TRUE...OTHERWISE...END.

o If a CASE expression is not present, any TRUE, FALSE, or NULL blocks are
  ignored.


ΓòÉΓòÉΓòÉ 203. UNIQUE() ΓòÉΓòÉΓòÉ

The UNIQUE() function returns a new string each time it is called.

            ΓöîΓöÇ"FTB__"ΓöÇΓöÉ   ΓöîΓöÇ20ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöÇΓöÇUNIQUE(ΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇ,ΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
            ΓööΓöÇstemΓöÇΓöÇΓöÇΓöÇΓöÿ   ΓööΓöÇlengthΓöÇΓöÿ

Examples

More about UNIQUE()


ΓòÉΓòÉΓòÉ 203.1. Examples ΓòÉΓòÉΓòÉ

x = UNIQUE("$temp",10)  ! Similar to "$temp____1"
x = UNIQUE(,6)          ! Similar to "FTB__2"
x = UNIQUE()            ! Similar to "FTB__...__3"

Examples source library:


ΓòÉΓòÉΓòÉ 203.2. More about UNIQUE() ΓòÉΓòÉΓòÉ

o Care must be taken to guard against the possibility of duplicate strings.
  Although UNIQUE() never returns the same string twice within the same
  session, it may by chance generate a string which is already in use as a
  table name, file name, or some other entity. Similarly, it is possible for a
  programmer to create a string that has already been generated by UNIQUE().

  To avoid this problem, always specify a stem for UNIQUE() that you never use
  in any other context.


ΓòÉΓòÉΓòÉ 204. UNTIL ΓòÉΓòÉΓòÉ

The UNTIL statement specifies a condition which causes one or more statements
following it to be executed repeatedly until the condition is true.

ΓöÇΓöÇUNTILΓöÇΓöÇexpressionΓöÇΓöÇstatementlistΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Examples

More about UNTIL

See also: ITERATE, TERMINATE, WHILE


ΓòÉΓòÉΓòÉ 204.1. Examples ΓòÉΓòÉΓòÉ

DECLARE NUMERIC value     = 0
DECLARE NUMERIC increment = 1
DECLARE NUMERIC totval    = 0
UNTIL value>100
DO
  LET value += increment
  LET increment += 1
  LET totval += value
END

Examples source library:


ΓòÉΓòÉΓòÉ 204.2. More about UNTIL ΓòÉΓòÉΓòÉ

o An UNTIL statement can control a single statement or a set of statements. A
  set of statements must be enclosed in a DO ... END block.

o The statements controlled by the UNTIL statement are always executed at least
  once.  expression is not executed on entry to the loop.

o ITERATE and TERMINATE statements can be used to modify the behavior of the
  UNTIL loop.


ΓòÉΓòÉΓòÉ 205. UPPER() ΓòÉΓòÉΓòÉ

The UPPER() function converts all lowercase letters in a string to uppercase.

ΓöÇΓöÇUPPER(string)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Examples

More about UPPER()


ΓòÉΓòÉΓòÉ 205.1. Examples ΓòÉΓòÉΓòÉ

x = UPPER("Books")   ! x is "BOOKS"
x = UPPER("BБcher")  ! x is "BЪCHER"

Examples source library:


ΓòÉΓòÉΓòÉ 205.2. More about UPPER() ΓòÉΓòÉΓòÉ

o Non-alphabetical and uppercase characters are not affected.

o The exact way that this function operates depends on the country setting and
  code page to which the system is set.

o Using a string parameter of type NULL in this function produces a result of
  NULL.


ΓòÉΓòÉΓòÉ 206. VALUE ΓòÉΓòÉΓòÉ

The VALUE object class creates an instance of a value set.

Parent: WINDOW

Attributes

Actions

Events

Examples

More about VALUE


ΓòÉΓòÉΓòÉ 206.1. Attributes ΓòÉΓòÉΓòÉ

CHECKED             COLS
ENABLED             HANDLES
HELP                ITEMLIST
ITEMTYPE            ORIGIN
RESOURCE            ROWS
SCALE               SIZEX
SIZEY               VISIBLE
X                   Y


ΓòÉΓòÉΓòÉ 206.1.1. CHECKED ΓòÉΓòÉΓòÉ

Item number of the selected item.

Default: 0 (No item selected) Once an item has been selected, CHECKED cannot be
reassigned to 0 to indicate no item selected. One of the items must be
selected, therefore the range is now 1 to number of items.


ΓòÉΓòÉΓòÉ 206.1.2. COLS ΓòÉΓòÉΓòÉ

Number of columns per set.  An integer, read-only after open.

Default: 0


ΓòÉΓòÉΓòÉ 206.1.3. ENABLED ΓòÉΓòÉΓòÉ

0         Item grayed out and not selectable
1         Item enabled

Default: 1 (Enabled)


ΓòÉΓòÉΓòÉ 206.1.4. HANDLES ΓòÉΓòÉΓòÉ

Whether sizing handles are attached to the value set to support moving, sizing,
and copying operations. These direct manipulation techniques follow the CUA
guidelines. See also the AUTOSELECT attribute of the WINDOW object.

0         Handles are not displayed
1         Handles are displayed

Default: 0 (No handles)


ΓòÉΓòÉΓòÉ 206.1.5. HELP ΓòÉΓòÉΓòÉ

Resource identifier (res ID) of the full help text for this object.

Default: 0


ΓòÉΓòÉΓòÉ 206.1.6. ITEMLIST ΓòÉΓòÉΓòÉ

Pointer to the contents of a vector of text strings (if text is being used) or
a pointer to the contents of a vector of bitmap names and locations (if bitmap
files are being used).

If DLL files are being used, ITEMLIST contains the name of a vector which holds
the res IDs of the items in the DLL.

Default: ""


ΓòÉΓòÉΓòÉ 206.1.7. ITEMTYPE ΓòÉΓòÉΓòÉ

Whether items are text or bitmap :

0         Text: each item should evaluate to a text string
1         Bitmap: each item should evaluate to the name of a BMP bitmap file
2         Color: the bitmap will be displayed using the color palette.

Set on OPEN, then read-only.

Default: 0 (Text)


ΓòÉΓòÉΓòÉ 206.1.8. ORIGIN ΓòÉΓòÉΓòÉ

The corner of the enclosing window to be taken as the origin.  The position of
the object is measured from this point.

"TL"      Top left
"TR"      Top right
"BL"      Bottom left
"BR"      Bottom right

Default: "BL" (Bottom left)


ΓòÉΓòÉΓòÉ 206.1.9. RESOURCE ΓòÉΓòÉΓòÉ

Name of DLL file (including the path name if required) when DLL files are used
instead of BMP files.

Default: None


ΓòÉΓòÉΓòÉ 206.1.10. ROWS ΓòÉΓòÉΓòÉ

Number of rows per set. An integer. Set on OPEN, then read-only.

Default: 1


ΓòÉΓòÉΓòÉ 206.1.11. SCALE ΓòÉΓòÉΓòÉ

If 1, bitmaps are scaled to fit in value cells. If 0, the default size is
displayed.

Default: 0


ΓòÉΓòÉΓòÉ 206.1.12. SIZEX ΓòÉΓòÉΓòÉ

Width, in dialog box units.

Default: 0


ΓòÉΓòÉΓòÉ 206.1.13. SIZEY ΓòÉΓòÉΓòÉ

Height, in dialog box units.

Default: 0


ΓòÉΓòÉΓòÉ 206.1.14. VISIBLE ΓòÉΓòÉΓòÉ

Whether the item is displayed or not:

0         Item not displayed.
1         Item displayed.

Default: 1 (Displayed)


ΓòÉΓòÉΓòÉ 206.1.15. X ΓòÉΓòÉΓòÉ

Horizontal position in dialog box units.

Default: 0


ΓòÉΓòÉΓòÉ 206.1.16. Y ΓòÉΓòÉΓòÉ

Vertical position in dialog box units.

Default: 0


ΓòÉΓòÉΓòÉ 206.2. Actions ΓòÉΓòÉΓòÉ

DISABLE()            EDIT()
ENABLE()             REFRESH()


ΓòÉΓòÉΓòÉ 206.2.1. DISABLE() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇDISABLE(item_number)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Disables value set item.


ΓòÉΓòÉΓòÉ 206.2.2. EDIT() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇEDIT(argument)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Enables the programmer to query whether a clipboard operation is supported and,
if it is, to carry it out.

argument is a clipboard query or a clipboard operation.

The following values for argument are used to check whether particular
clipboard operations can be supported with the value set in its current state:

"Querycut" Cut to clipboard
"Querycopy" Copy to clipboard
"Querypaste" Paste from clipboard
"Queryclear" Clear clipboard.

Where clipboard operations are supported, the following values for argument
direct them to be carried out:

"Cut"     Cut to clipboard
"Copy"    Copy to clipboard
"Paste"   Paste from clipboard
"Clear"   Clear clipboard.


ΓòÉΓòÉΓòÉ 206.2.3. ENABLE() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇENABLE(item_number)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Enables value set item.


ΓòÉΓòÉΓòÉ 206.2.4. REFRESH() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇREFRESH()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Forces repainting of the value set on screen.


ΓòÉΓòÉΓòÉ 206.3. Events ΓòÉΓòÉΓòÉ

DESKTOP            SELECT


ΓòÉΓòÉΓòÉ 206.3.1. DESKTOP ΓòÉΓòÉΓòÉ

Signaled when the value set is moved, sized, or copied. A.System.Operation is
set to "MOVE", "SIZE", or "COPY". A.System.Object contains the name of the
control.


ΓòÉΓòÉΓòÉ 206.3.2. SELECT ΓòÉΓòÉΓòÉ

Signals the ON SELECT block. A.System.Object is set to named control. Use the
CHECKED attribute to identify which box was selected.  LET box =
T..Value1'CHECKED


ΓòÉΓòÉΓòÉ 206.4. Examples ΓòÉΓòÉΓòÉ

!
! Open a simple value set.
!
PROCEDURE VALUE
DO
  LET daylist="days[1]"
  OPEN value value1,sampwind,
   x=40,y=40,                     ! position
   itemlist=daylist,              ! reference array
   sizex=120,sizey=120,           ! size
   visible=1,                     ! enabled
   rows=5,                        ! number of choices (vertical)
   cols=1,                        ! number of choices (horizontal)
   text="Weekdays",               ! title for value set
   itemtype=0,                    ! items will be text
   origin="bl"                    ! relative position
  !
  LET value1'CHECKED=3
  ! Disable (gray) the fifth item
  CALL value1'DISABLE(5)
END

The code below shows how to fill a vector containing bitmap information:

 DEFINE valuearr[4]
 LET valuearr[1]="d:\icons\AS1.BMP"
 LET valuearr[2]="d:\icons\AS2.BMP"
 LET valuearr[3]="d:\icons\AS3.BMP"
 LET valuearr[4]="d:\icons\AS4.BMP"
 LET valuelst="valuearr[1]"
 OPEN VALUE, myvalue,
      ITEMLIST = valuelst
      . . .

Examples source library:


ΓòÉΓòÉΓòÉ 206.5. More about VALUE ΓòÉΓòÉΓòÉ

o The VALUE object cannot be cloned.


ΓòÉΓòÉΓòÉ 207. VALUE() ΓòÉΓòÉΓòÉ

The VALUE() function returns the first of its arguments which is not NULL.

           <ΓöÇ,ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöÇΓöÇVALUE(ΓöÇΓöÇΓöÇvalueΓöÇΓö┤ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Examples

More about VALUE()


ΓòÉΓòÉΓòÉ 207.1. Examples ΓòÉΓòÉΓòÉ

DEFINE Array[5]
x = VALUE( Array[3], -1 )  ! Result is -1
x = VALUE( Array[0], -1 )  ! Result is -1
Array[4] = 42
x = VALUE( Array[3], -1 )  ! Result is -1
x = VALUE( Array[0], -1 )  ! Result is 42
Array[2] = 8.12
x = VALUE( Array[0], -1 )  ! Result is 8.12

Examples source library:


ΓòÉΓòÉΓòÉ 207.2. More about VALUE() ΓòÉΓòÉΓòÉ

o If all the values are NULL, the result is also NULL.


ΓòÉΓòÉΓòÉ 208. VARIANCE() ΓòÉΓòÉΓòÉ

The VARIANCE() function returns an estimate of the variance based on a sample
of values.

ΓöÇΓöÇVARIANCE(array)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Examples

More about VARIANCE()


ΓòÉΓòÉΓòÉ 208.1. Examples ΓòÉΓòÉΓòÉ

x = VARIANCE(set)

Examples source library:


ΓòÉΓòÉΓòÉ 208.2. More about VARIANCE() ΓòÉΓòÉΓòÉ

o VARIANCE() is calculated by summing the squared deviations of each value from
  the arithmetic mean, and dividing by the number of values in the sample minus
  one.


ΓòÉΓòÉΓòÉ 209. VERIFY() ΓòÉΓòÉΓòÉ

The VERIFY() function checks whether each individual element of a vector array
is, or can be converted to, a specified data type. If all elements can be
converted, VERIFY() returns 0. Otherwise it returns the position of the first
element which cannot be converted.

                         ΓöîΓöÇ1ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ                 ΓöîΓöÇ"="ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöÇΓöÇVERIFY(ref,content,ΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇ,ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇ,ΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇ,ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                         ΓööΓöÇstartΓöÇΓöÿ     ΓööΓöÇendΓöÇΓöÿ     ΓööΓöÇcompareΓöÇΓöÿ
   ΓöîΓöÇ0ΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
   ΓööΓöÇnullΓöÇΓöÿ

Examples

More about VERIFY()


ΓòÉΓòÉΓòÉ 209.1. Examples ΓòÉΓòÉΓòÉ

o If vector is:

    vector[1] = 5
    vector[2] = 18.2
    vector[3] = "Fred"
    vector[4] = 8.12
    vector[5] = 1024

  and the content of num is numeric, then the statement  VERIFY(vector,num)
  returns 3 (the position of the element that is not numeric and cannot be
  converted).

o If vector is:

    vector[1] = "a"
    vector[2] = "b"
    vector[3] = "c"
    vector[4] = 3
    vector[5] = "e"

  and the content of num is numeric, then the statement
  VERIFY(vector,num,,,"\=") returns 4 (the position of the element that is
  numeric).

o If vector is:

    vector[1] = 9
    vector[2] = 8
    vector[3] = "7"
    vector[4] = 6
    vector[5] = 5

  and the content of num is numeric, then the statement
  VERIFY(vector,num,,,"==") returns 3, because, although "7" could be converted
  to numeric type, the "==" test comparison forbids conversion.

Examples source library:


ΓòÉΓòÉΓòÉ 209.2. More about VERIFY() ΓòÉΓòÉΓòÉ

o The "\=" comparison reverses the VERIFY() so that it checks for elements that
  cannot be converted to the specified data type. This is useful in searching
  for NULL elements within an array.

o If the values given in the start and end parameters fall outside the range of
  the array, then VERIFY() returns zero.


ΓòÉΓòÉΓòÉ 210. VIEWCALCS ΓòÉΓòÉΓòÉ

The ViewCalcs object is used in conjunction with the IBMDATA object to allow
the use of calculated columns. The Calculate columns window allows the user to
set the column type, format, and name.

Attributes

Actions

Events: None.

Examples

More about

See also: IBMDATA, VIEWORDER, VIEWROWS, VIEWTABLES


ΓòÉΓòÉΓòÉ 210.1. Attributes ΓòÉΓòÉΓòÉ

OWNERWINDOW            DATA
MODAL


ΓòÉΓòÉΓòÉ 210.1.1. OWNERWINDOW ΓòÉΓòÉΓòÉ

This is a pointer to the window of the parent application.


ΓòÉΓòÉΓòÉ 210.1.2. DATA ΓòÉΓòÉΓòÉ

This is a pointer to the underlying data object. Messages are sent to the data
object to find the initial set of calculated columns. If changes are made, the
underlying data object is then updated with the latest calculations.


ΓòÉΓòÉΓòÉ 210.1.3. MODAL ΓòÉΓòÉΓòÉ

Defines whether or not the window is modal.

0         Window not modal
1         Window modal.

Default: 0 (Not modal)


ΓòÉΓòÉΓòÉ 210.2. Actions ΓòÉΓòÉΓòÉ

SURFACE()


ΓòÉΓòÉΓòÉ 210.2.1. SURFACE() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSURFACE()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

If this action is called the window showing the selected rows will be brought
to the top of the glass.


ΓòÉΓòÉΓòÉ 210.3. Examples ΓòÉΓòÉΓòÉ

Example of opening a VIEWCALCS object.

When a selection is made on the menu for Calculate Columns, the application
will open the Calculate columns view object.

ON SELECT
DO
  CASE A.System.Object             ! Which screen object?
    WHEN "T.Primary.CalcCols"      ! Calc cols selected.
    DO
      IF NULL(MyVCalcs'CLASS)      ! If object is not open
      THEN
        OPEN VIEWCALCS MyVCalcs,   ! then open it
         OWNERWINDOW  = POINTER( Primary[0] ),
         DATA         = POINTER( MyData[0] )
      ELSE
        CALL MyVCalcs'SURFACE()    ! else just surface it.
    END
  END
END

Add the following code in the ON QUIT block to handle shutting down the data
object.

IF A.System.Object = "T..MyVCalcs"
THEN DO
  SHUT MyVCalcs    ! Close ViewCalcs window
  CALL MyData'SNAPSHOT( Pointer( mycopy[0] ), "*" )
  IF MyData'CODE = 0  ! If it worked...
  THEN ...

Examples source library:


ΓòÉΓòÉΓòÉ 210.4. More about ΓòÉΓòÉΓòÉ

o AS/400 calculations are evaluated in Visualizer by Query.

o IBMSQLSTATEMENT calculations use ASL syntax.


ΓòÉΓòÉΓòÉ 211. VIEWORDER ΓòÉΓòÉΓòÉ

The ViewOrder object is used in conjunction with the IBMDATA object to provide
a order rows interface and an index feature.

Attributes

Actions

Events

Examples

See also: IBMDATA, VIEWCALCS, VIEWROWS, VIEWTABLES


ΓòÉΓòÉΓòÉ 211.1. Attributes ΓòÉΓòÉΓòÉ

OWNERWINDOW            DATA
MODAL                  TITLE
TABLE                  ORDERVECTOR
ORDERSIGNS             VISIBLE
CODE


ΓòÉΓòÉΓòÉ 211.1.1. OWNERWINDOW ΓòÉΓòÉΓòÉ

This is a pointer to the window of the parent application.


ΓòÉΓòÉΓòÉ 211.1.2. DATA ΓòÉΓòÉΓòÉ

This is a pointer to the underlying data object.  Messages are sent to the data
object to find the initial set order. Use DATA if the ordering is for a data
object, if for a table use the TABLE attribute.


ΓòÉΓòÉΓòÉ 211.1.3. MODAL ΓòÉΓòÉΓòÉ

Defines whether or not the window is modal.

0         Window not modal
1         Window modal

Default: 0 (Not modal)


ΓòÉΓòÉΓòÉ 211.1.4. TITLE ΓòÉΓòÉΓòÉ

The title to be used on the window.


ΓòÉΓòÉΓòÉ 211.1.5. TABLE ΓòÉΓòÉΓòÉ

Pointer to the table handle. Use TABLE if the ordering is for a table object,
if for a DATA object  use the DATA attribute.


ΓòÉΓòÉΓòÉ 211.1.6. ORDERVECTOR ΓòÉΓòÉΓòÉ

Pointer to vector of order names.


ΓòÉΓòÉΓòÉ 211.1.7. ORDERSIGNS ΓòÉΓòÉΓòÉ

Pointer to vector of order signs.


ΓòÉΓòÉΓòÉ 211.1.8. VISIBLE ΓòÉΓòÉΓòÉ

Whether the order window is visible.

Default: 0 (Not visible)


ΓòÉΓòÉΓòÉ 211.1.9. CODE ΓòÉΓòÉΓòÉ

The return code from the last action.


ΓòÉΓòÉΓòÉ 211.2. Actions ΓòÉΓòÉΓòÉ

ORDER()


ΓòÉΓòÉΓòÉ 211.2.1. ORDER() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇORDER(p_index)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Produces an index based on OrderVector and OrderSigns p_index is a pointer to a
vector which holds the index information.


ΓòÉΓòÉΓòÉ 211.3. Events ΓòÉΓòÉΓòÉ

ORDER


ΓòÉΓòÉΓòÉ 211.3.1. ORDER ΓòÉΓòÉΓòÉ

Signaled when Order is selected.


ΓòÉΓòÉΓòÉ 211.4. Examples ΓòÉΓòÉΓòÉ

The application will typically get a selection from a pull down which indicates
that an ordering based on column rows needs to be performed.Code to perform
this function is shown below:

ON SELECT
DO
  CASE A.System.Object
    WHEN "T.Primary.Order"
    DO
      ! User needs to order rows, so open up view order object,
      ! passing a pointer to the data table (which must already
      ! be open), and a pointer to the main display window
      ! (ownerwindow).   The pointers are also passed to two
      ! arrays, which may be empty, to specify the order columns
      ! and signs ("A" for ascending, "D" for descending).
      IF NULL(Order'CLASS)
      THEN
        OPEN VIEWORDER  Order,
         TABLE       = POINTER( MyTab[0] ),
         VISIBLE     = 1,
         OWNERWINDOW = POINTER( MyWin[0] ),
         ORDERVECTOR = POINTER( OrderVector[0] ),
         ORDERSIGNS  = POINTER( OrderSigns[0] )
      ELSE
        LET Order'VISIBLE = 1  ! Already open, so display it
    END
  END
END

When the user completes the selection and selects Order, the order event will
be triggered. The ASL code can then react to the order action to produce an
index to order the data. The user selections will be in the vectors passed as
OrderVector and OrderSigns.

The Order object will continue to exist but its window will be hidden. You may
wish to SHUT the object, or leave it for the next selection on Order. The code
for the Order event is shown below:

ON ORDER
DO
  ! Set up Index to contain an index to sort the data
  CALL Order'ORDER( POINTER( Index[0] ) )
END

If the user selected Cancel or tried to exit the application, a test can be
placed in the QUIT block to ignore the selection or close the object:

ON QUIT
DO
  IF A.System.Object = "T..Order"
  THEN SHUT Order          ! Shut the ViewOrder object
END

Examples source library:


ΓòÉΓòÉΓòÉ 212. VIEWPORT ΓòÉΓòÉΓòÉ

The VIEWPORT object class allows the display of graphics in metafile format
within graphic boxes.

Parent: GRAPHIC

Attributes

Actions: None.

Events: None.

Examples

More about VIEWPORT


ΓòÉΓòÉΓòÉ 212.1. Attributes ΓòÉΓòÉΓòÉ

UNIFORM             METAFILE
SIZEX               SIZEY
X                   Y
ZORDER


ΓòÉΓòÉΓòÉ 212.1.1. UNIFORM ΓòÉΓòÉΓòÉ

Whether the aspect ratio of the graphic area is maintained.  If the aspect
ratio is ignored, the graphic area is adapted to fill the display space
available.

0         Aspect ratio ignored (image distorted)
1         Aspect ratio maintained (may leave unused space within the graphic
          area)

Default: 0 (Ignored)


ΓòÉΓòÉΓòÉ 212.1.2. METAFILE ΓòÉΓòÉΓòÉ

Location (operating system path, with extension) and full filename of the
metafile.

If METAFILE is set to "CLIPBOARD", VIEWPORT will use any metafile which has
been saved to the clipboard.

Set on OPEN, then read-only.

Default: ""


ΓòÉΓòÉΓòÉ 212.1.3. SIZEX ΓòÉΓòÉΓòÉ

Horizontal size of the viewport, in world coordinates.

Default: 0


ΓòÉΓòÉΓòÉ 212.1.4. SIZEY ΓòÉΓòÉΓòÉ

Vertical size of the viewport, in world coordinates.

Default: 0


ΓòÉΓòÉΓòÉ 212.1.5. X ΓòÉΓòÉΓòÉ

Horizontal position in world coordinates.

Default: 0


ΓòÉΓòÉΓòÉ 212.1.6. Y ΓòÉΓòÉΓòÉ

Vertical position in world coordinates.

Default: 0


ΓòÉΓòÉΓòÉ 212.1.7. ZORDER ΓòÉΓòÉΓòÉ

Where the graphic is drawn:

0         Graphic is drawn below any other shapes
1         Graphic is drawn above other shapes

Default: 1 (Above)


ΓòÉΓòÉΓòÉ 212.2. Examples ΓòÉΓòÉΓòÉ

Using VIEWPORT to display a metafile.

OPEN WINDOW MyWin,, Title="Display a metafile",
 SIZEX = 400, SIZEY = 200
OPEN GRAPHIC Graphbox, MyWin,
 SIZEX = 400, SIZEY = 200, X = 0, Y = -200,
 WCSMAXX =400, WCSMAXY = 200,
 ORIGIN = "TL"

! Open the viewport and place the metafile in it
OPEN VIEWPORT Viewport, Graphbox,
 METAFILE = "C:\FISH\HADDOCK.MET",
 X = 0, Y = 0, SIZEX = 400, SIZEY = 200,
 UNIFORM = 0, ZORDER = 1

! Called when the user resizes the window.
ON DESKTOP
DO
  LET graphbox'VISIBLE = 0 ! Hide the area

  ! Set the new graphic area size and position, based on the new
  ! window size.  Y is negative since origin is top left.
  LET graphbox'Y     = -Mywin'SIZEY
  LET graphbox'SIZEX =  Mywin'SIZEX
  LET graphbox'SIZEY =  Mywin'SIZEY

  LET graphbox'VISIBLE = 1 ! Show the area
END

Examples source library:


ΓòÉΓòÉΓòÉ 212.3. More about VIEWPORT ΓòÉΓòÉΓòÉ

o If you save a graphics area to a metafile, any information placed in the
  graphic area by VIEWPORT will not be saved in the metafile.


ΓòÉΓòÉΓòÉ 213. VIEWROWS ΓòÉΓòÉΓòÉ

The ViewRows object is used in conjunction with the IBMDATA object to allow the
use of multiple row selection. The Select rows window allows the user to enter
multiple row selection expressions on a single line.

Attributes

Actions

Events: None.

Examples

More about VIEWROWS

See also: IBMDATA, VIEWCALCS, VIEWORDER, VIEWTABLES


ΓòÉΓòÉΓòÉ 213.1. Attributes ΓòÉΓòÉΓòÉ

OWNERWINDOW            DATA
MODAL


ΓòÉΓòÉΓòÉ 213.1.1. OWNERWINDOW ΓòÉΓòÉΓòÉ

This is a pointer to the window of the parent application.,


ΓòÉΓòÉΓòÉ 213.1.2. DATA ΓòÉΓòÉΓòÉ

This is a pointer to the underlying data object. Messages are sent to the data
object to find the initial set of calculated columns. If changes are made, the
underlying data object is then updated with the latest calculations.


ΓòÉΓòÉΓòÉ 213.1.3. MODAL ΓòÉΓòÉΓòÉ

Defines whether or not the window is modal.

0         Window not modal
1         Window modal.

Default: 0 (Not modal)


ΓòÉΓòÉΓòÉ 213.2. Actions ΓòÉΓòÉΓòÉ

SURFACE()


ΓòÉΓòÉΓòÉ 213.2.1. SURFACE() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSURFACE()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

If this action is called, the window showing the selected rows will be made the
active window and given keyboard focus.


ΓòÉΓòÉΓòÉ 213.3. Examples ΓòÉΓòÉΓòÉ

Using IBMDATA with a Select rows window

Open the IBMDATA object as in the examples in IBMDATA. Then, to use a selection
which needs Select rows window to be surfaced, add the following code

OPEN VIEWROWS myrows,
  OWNERWINDOW = POINTER( MyAppWin[0] ),
  DATA        = POINTER( MyData[0] )

and in the ON QUIT block:

ON QUIT
DO
  IF A.System.Object = "T..myrows"
  THEN DO
    SHUT myrows    ! Close Select rows window
    CALL MyData'SNAPSHOT( POINTER( mycopy[0] ), "*")
    ...
  END
END

Examples source library:


ΓòÉΓòÉΓòÉ 213.4. More about VIEWROWS ΓòÉΓòÉΓòÉ

The expressions' evaluation depends on the FILINGSYSTEM of the IBMDATA object:

o Host expressions are evaluated on the host.
o OS/2 SQL expressions are evaluated in SQL.
o External OS/2 file expressions are evaluated by Query.
o AS/400 selections are evaluated on AS/400.
o IBMSQLSTATEMENT selections use ASL syntax.


ΓòÉΓòÉΓòÉ 214. VIEWTABLES ΓòÉΓòÉΓòÉ

VIEWTABLES presents a selectable list of tables. This object is used (together
with IBMDATA) to access information in tables.

Attributes

Actions

Events: None.

Examples

See also: IBMDATA, VIEWCALCS, VIEWROWS, VIEWORDER


ΓòÉΓòÉΓòÉ 214.1. Attributes ΓòÉΓòÉΓòÉ

OWNERWINDOW            DATA
TITLE                  MODAL
LISTTYPES


ΓòÉΓòÉΓòÉ 214.1.1. OWNERWINDOW ΓòÉΓòÉΓòÉ

Pointer to your main window.


ΓòÉΓòÉΓòÉ 214.1.2. DATA ΓòÉΓòÉΓòÉ

Pointer to an open data object. (mandatory)


ΓòÉΓòÉΓòÉ 214.1.3. TITLE ΓòÉΓòÉΓòÉ

Optional title.


ΓòÉΓòÉΓòÉ 214.1.4. MODAL ΓòÉΓòÉΓòÉ

Make window modal (optional)

0         Window not modal
1         Window modal.

Default: 0 (Not modal)


ΓòÉΓòÉΓòÉ 214.1.5. LISTTYPES ΓòÉΓòÉΓòÉ

Pointer to a restricted list of types. (optional)


ΓòÉΓòÉΓòÉ 214.2. Actions ΓòÉΓòÉΓòÉ

SURFACE()


ΓòÉΓòÉΓòÉ 214.2.1. SURFACE() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSURFACE()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

If this action is called, the window showing the selected table will be made
the active window and given keyboard focus.


ΓòÉΓòÉΓòÉ 214.3. Examples ΓòÉΓòÉΓòÉ

ON SELECT
DO
  CASE A.System.Object
    WHEN "Tables" ! Selection on 'Select table' menu
    DO
      IF NULL(ViewTab'CLASS)
      THEN DO
        DEFINE Types[0]
        ! You may define a vector which lists the types
        ! you want to show.  All types will be shown if the
        ! vector is omitted.  See IBMDATA for filing types
        INSERT Types[0] = "Host"
        INSERT Types[0] = "PRODUCT"
        INSERT Types[0] = "SQL"
        INSERT Types[0] = "AS400"

        OPEN ViewTables ViewTab,
          OWNERWINDOW  = POINTER( Window[0] ),  ! Main window.
          DATA         = POINTER( DataObj[0] ), ! Open data object.
          TITLE        = "Pick your own"        ! Your title
          LISTTYPES    = POINTER( Types[0] )    ! Restrict types
      END
      ELSE
        CALL ViewTab'SURFACE()
    END
  END
END

ON QUIT
DO
  ! If you get an on quit from the select table window, this may be
  ! due to a OK or CANCEL.  If OK was pressed, the TABLE, PATH and
  ! FILINGSYSTEM attributes of the data object will have been updated
  ! for you. You need to shut the View Table object.
  IF A.System.Object = "T..ViewTab"
  THEN DO
    SHUT T..ViewTab
    ! Then check table selection and process it
  END
END

Examples source library:


ΓòÉΓòÉΓòÉ 215. WAIT PROGRAM ΓòÉΓòÉΓòÉ

The WAIT PROGRAM statement waits for another program to complete.

ΓöÇΓöÇWAITΓöÇΓöÇPROGRAMΓöÇΓöÇprogramaliasΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Examples

More about WAIT PROGRAM

See also: QUEUE PROGRAM, SIGNAL PROGRAM, START


ΓòÉΓòÉΓòÉ 215.1. Examples ΓòÉΓòÉΓòÉ

START PROGRAM Conversion, 'I.Modules.Conversion'
...
WAIT PROGRAM Conversion

QUEUE PROGRAM Setup
QUEUE PROGRAM Setup,STOP
WAIT  PROGRAM Setup

Examples source library:


ΓòÉΓòÉΓòÉ 215.2. More about WAIT PROGRAM ΓòÉΓòÉΓòÉ

o The program that uses WAIT is suspended until the one for which it is waiting
  uses SIGNAL PROGRAM, or stops.

o WAIT can be used to synchronize two programs.  In the first example above, it
  might be used to wait until the Conversion program has received some input
  from the user.


ΓòÉΓòÉΓòÉ 216. WHEN ΓòÉΓòÉΓòÉ

The WHEN statement identifies a potential value of a CASE expression. When the
expression takes on that value, the statement or DO...END block following WHEN
is executed.

ΓöÇΓöÇWHENΓöÇΓöÇexpressionΓöÇΓöÇstatementlistΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Examples

More about WHEN

See also: CASE...WHEN...OTHERWISE...END, OTHERWISE


ΓòÉΓòÉΓòÉ 216.1. Examples ΓòÉΓòÉΓòÉ

CASE A.System.Object
  WHEN "SAVE"
    MESSAGE "FTB0001",0,"1 - Saved ...."
  WHEN "LOAD"
    MESSAGE "FTB0001",0,"1 - Loaded ..."
  OTHERWISE
    MESSAGE "FTB0001",0,"1 - Otherwise"
END

Examples source library:


ΓòÉΓòÉΓòÉ 216.2. More about WHEN ΓòÉΓòÉΓòÉ

o Any number of WHEN statements can be defined for a single CASE statement.

o The WHEN statements within a CASE construct can be followed by an OTHERWISE
  statement.  The OTHERWISE statement deals with all values not explicitly
  identified by any of the WHEN statements. (See the entry for the OTHERWISE
  statement.)

o The WHEN expression is executed first and the result is compared with the
  result of the CASE expression.  If no CASE expression is supplied, the WHEN
  expression is checked for being true (nonzero).

o If a CASE expression is present and a WHEN specifies a comparison, the CASE
  expression is compared with the result of the comparison. The WHEN is not
  controlled by the comparison alone, for example:

    X = 3
    CASE 2
      WHEN X = 3

  In this case the WHEN clause never matches because the comparison  X=3
  evaluates to either true or false (1 or 0), and is never equal to 2.

o Only one WHEN statement (the first one for which the condition is true) is
  executed for a given execution of the CASE statement.


ΓòÉΓòÉΓòÉ 217. WHILE ΓòÉΓòÉΓòÉ

The WHILE statement specifies a condition which causes one or more statements
following it to be executed repeatedly for as long as the condition exists.

ΓöÇΓöÇWHILEΓöÇΓöÇexpressionΓöÇΓöÇstatementlistΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Examples

More about WHILE

See also: ITERATE, TERMINATE, UNTIL


ΓòÉΓòÉΓòÉ 217.1. Examples ΓòÉΓòÉΓòÉ

DECLARE NUMERIC value     = 0
DECLARE NUMERIC increment = 1
DECLARE NUMERIC totval    = 0
WHILE value<100
DO
  LET value += increment
  LET increment += 1
  LET totval += value
END

Examples source library:


ΓòÉΓòÉΓòÉ 217.2. More about WHILE ΓòÉΓòÉΓòÉ

o If a set of statements is controlled by the WHILE statement, then they must
  be enclosed in a DO...END block.

o If the expression is false when the WHILE statement is first met, the
  statement list is not executed at all.

o The ITERATE and TERMINATE statements can be used to modify the behavior of
  the WHILE loop.


ΓòÉΓòÉΓòÉ 218. WINDOW ΓòÉΓòÉΓòÉ

The WINDOW object class creates a window on screen.

Attributes

Actions

Events

Examples


ΓòÉΓòÉΓòÉ 218.1. Attributes ΓòÉΓòÉΓòÉ

AUTOSELECT              BGCOLOR
BORDER                  CURSORBOX
CURSORCLONE             FGCOLOR
FONT                    GRIDX
GRIDY                   HEIGHT
HELP                    HSCRLBAR
HSCRLBARPOSN            HTHUMBSIZE
ICON                    MAXX
MAXY                    MENUREF
MINMAX                  MINX
MINY                    MODAL
OBJECTVIEW              OWNERWINDOW
PATTERN                 SELECTABLE
SIZEX                   SIZEY
SOURCECTRL              SYSMENU
TARGETCTRL              TARGETX
TARGETY                 TITLE
TITLEBAR                VISIBLE
VSCRLBAR                VSCRLBARPOSN
VTHUMBSIZE              WIDTH
X                       Y


ΓòÉΓòÉΓòÉ 218.1.1. AUTOSELECT ΓòÉΓòÉΓòÉ

Specifies whether the selection of controls on the window follows the CUA
extended selection model. Only those controls that have a HANDLES attribute set
are included in extended selection operations.

0         Extended selection techniques are not supported
1         Extended selection techniques are supported

Note:   This attribute is for specialist applications only. When AUTOSELECT is
        set to 1, the window cannot be used as an ordinary application window.

Default: 0


ΓòÉΓòÉΓòÉ 218.1.2. BGCOLOR ΓòÉΓòÉΓòÉ

Background color. Integer in the range 1-19. See Colors and color codes for
details of colors available. If BGCOLOR is set, this color will be passed to
all controls located on the window as the default color.

Default: System default color (set from control panel)


ΓòÉΓòÉΓòÉ 218.1.3. BORDER ΓòÉΓòÉΓòÉ

Window border style:

0         Normal sizing border
1         Dialog border
2         Thin line border
3         No border

Default: 0 (Normal sizing border)


ΓòÉΓòÉΓòÉ 218.1.4. CURSORBOX ΓòÉΓòÉΓòÉ

Name of the box that currently has cursor focus (the box the keyboard entry or
selection cursor is currently in).

This name must be in the format T.window.box, where window is the name of the
window object and box is the name of the box.

Default: Calculated by Presentation Manager.


ΓòÉΓòÉΓòÉ 218.1.5. CURSORCLONE ΓòÉΓòÉΓòÉ

Number of the clone the cursor is currently in.

Can be queried only.

Default: Calculated by Presentation Manager.


ΓòÉΓòÉΓòÉ 218.1.6. FGCOLOR ΓòÉΓòÉΓòÉ

Foreground color. Integer in the range 1-19. See Colors and color codes for
details of colors available.

Default: System default color (set from control panel)


ΓòÉΓòÉΓòÉ 218.1.7. FONT ΓòÉΓòÉΓòÉ

Text font. The available fonts are in the OS/2 font palette. The attribute
value is case sensitive. For example, Helv 10 point must be specified as
"10.Helv".

Default: System default font


ΓòÉΓòÉΓòÉ 218.1.8. GRIDX ΓòÉΓòÉΓòÉ

Horizontal units of underlying grid in dialog units. The window is moved and
resized using this grid.

Default: Calculated by Visualizer.


ΓòÉΓòÉΓòÉ 218.1.9. GRIDY ΓòÉΓòÉΓòÉ

Vertical units of underlying grid in dialog units. The window is moved and
resized using this grid.

Default: Calculated by Visualizer.


ΓòÉΓòÉΓòÉ 218.1.10. HEIGHT ΓòÉΓòÉΓòÉ

Height of the window, in millimeters.

Once the window is opened, the value is read-only.

Default: Calculated by Visualizer.


ΓòÉΓòÉΓòÉ 218.1.11. HELP ΓòÉΓòÉΓòÉ

The Resource identifier (res ID) of the full help text for this window.


ΓòÉΓòÉΓòÉ 218.1.12. HSCRLBAR ΓòÉΓòÉΓòÉ

Whether a horizontal scroll bar is included:

0         No scroll bar
1         Scroll bar

Default: 0 (No scroll bar)


ΓòÉΓòÉΓòÉ 218.1.13. HSCRLBARPOSN ΓòÉΓòÉΓòÉ

Position of horizontal scroll bar slider. Integer in the range 1-1000.

Default: 1 (Left)


ΓòÉΓòÉΓòÉ 218.1.14. HTHUMBSIZE ΓòÉΓòÉΓòÉ

Size of horizontal scroll bar thumb. Integer in the range 1-1000.

Can be modified but not queried.

Default: Calculated by Visualizer.


ΓòÉΓòÉΓòÉ 218.1.15. ICON ΓòÉΓòÉΓòÉ

The name of the associated icon: either the fully qualified name of an icon
file, or a string in the form dllname<id>, where dllname is the name of a DLL
and id is the resource ID of the icon within that DLL.

Default: NULL (Standard system menu icon)


ΓòÉΓòÉΓòÉ 218.1.16. MAXX ΓòÉΓòÉΓòÉ

Maximum horizontal size to which the window can be maximized. Integer value in
dialog box units.

If this value is greater than the maximum size, the Visualizer maximum is
applied.

Default: Calculated by Visualizer.


ΓòÉΓòÉΓòÉ 218.1.17. MAXY ΓòÉΓòÉΓòÉ

Maximum vertical size to which the window can be maximized. Integer value in
dialog box units. If this value is greater than the maximum size, the
Visualizer maximum is applied.

Default: Calculated by Visualizer.


ΓòÉΓòÉΓòÉ 218.1.18. MENUREF ΓòÉΓòÉΓòÉ

Name of a vector of menus to be used as the menu bar for the window.

Default: ""


ΓòÉΓòÉΓòÉ 218.1.19. MINMAX ΓòÉΓòÉΓòÉ

Whether minimize and maximize controls are provided for this window:

"MIN"     Minimize only
"MAX"     Maximize only
"MINMAX"  Minimize and maximize
"NONE"    No minmax controls

Default: "MINMAX"


ΓòÉΓòÉΓòÉ 218.1.20. MINX ΓòÉΓòÉΓòÉ

Minimum horizontal size to which the window can be minimized. Integer value in
dialog box units. If this value is less than the minimum size, the Visualizer
minimum is applied.

Default: Calculated by Visualizer.


ΓòÉΓòÉΓòÉ 218.1.21. MINY ΓòÉΓòÉΓòÉ

Minimum vertical size to which the window can be minimized. Integer value in
dialog box units. If this value is less than the minimum size, the Visualizer
minimum is applied.

Default: Calculated by Visualizer.


ΓòÉΓòÉΓòÉ 218.1.22. MODAL ΓòÉΓòÉΓòÉ

Defines whether or not the window is modal.

0         Window not modal
1         Window modal

Default: 0 (Not modal)

When a window is made modal, all other windows in this application are
disabled. Other applications are not affected.


ΓòÉΓòÉΓòÉ 218.1.23. OBJECTVIEW ΓòÉΓòÉΓòÉ

Boolean attribute that, if 1 (true), identifies the window to the system as the
target for any messages resulting from the user dragging the Workplace Shell
icon for the application. Dragging the icon of the object will be interpreted
as if the user had dragged the title bar of the opened object.

Only one window within a Visualizer process can have its OBJECTVIEW attribute
set to 1 (true).

Default: 0 (False)


ΓòÉΓòÉΓòÉ 218.1.24. OWNERWINDOW ΓòÉΓòÉΓòÉ

Name of the window that owns the current window (if any). When the named window
is moved or closed, the present window follows it.

Default: No owner window


ΓòÉΓòÉΓòÉ 218.1.25. PATTERN ΓòÉΓòÉΓòÉ

Pattern for the window background. Integer in the range 0-14. See
Patterns and patterncodes for details of patterns available.

Default: (Plain)


ΓòÉΓòÉΓòÉ 218.1.26. SELECTABLE ΓòÉΓòÉΓòÉ

Whether the window client area (central area) is selectable:

0         Client area not selectable
1         Client area selectable

Default: 0 (Not selectable)


ΓòÉΓòÉΓòÉ 218.1.27. SIZEX ΓòÉΓòÉΓòÉ

Width of the window, in dialog box units.

Default: Calculated by Presentation Manager.


ΓòÉΓòÉΓòÉ 218.1.28. SIZEY ΓòÉΓòÉΓòÉ

Height of the window, in dialog box units.

Default: Calculated by Presentation Manager.


ΓòÉΓòÉΓòÉ 218.1.29. SOURCECTRL ΓòÉΓòÉΓòÉ

This attribute can be assigned a pointer to a SOURCECTRL object to enable a
drag to be initiated from the title bar of the window.

Default: None


ΓòÉΓòÉΓòÉ 218.1.30. SYSMENU ΓòÉΓòÉΓòÉ

Whether a system menu is provided:

0         No system menu
1         System menu provided

Default: 1 (System menu provided)


ΓòÉΓòÉΓòÉ 218.1.31. TARGETCTRL ΓòÉΓòÉΓòÉ

This attribute can be assigned a pointer to a TARGETCTRL object to enable other
objects to be dropped anywhere on the window client area (providing the ASL
thread owning the window is not busy).

When an object is validly dropped on a window client area or title bar (but not
a frame control or menu bar), then a TARGET event is signaled.

The ORIGINATOR attribute of the STREAM object passed with the TARGET event
identifies the TARGETCTRL object through which the event was generated.

The ORIGINATOR attribute of the TARGETCTRL object identifies the target window.

Default: None


ΓòÉΓòÉΓòÉ 218.1.32. TARGETX ΓòÉΓòÉΓòÉ

Horizontal position,in dialog units, of a drop within the client area. If the
drop occurs on any part of the window frame, TARGETX will return NULL.


ΓòÉΓòÉΓòÉ 218.1.33. TARGETY ΓòÉΓòÉΓòÉ

Vertical position,in dialog units, of a drop within the client area. If the
drop occurs on any part of the window frame, TARGETY will return NULL.


ΓòÉΓòÉΓòÉ 218.1.34. TITLE ΓòÉΓòÉΓòÉ

Title of the window, displayed in the title bar. String enclosed in double
quotation marks.

Default: No title in title bar


ΓòÉΓòÉΓòÉ 218.1.35. TITLEBAR ΓòÉΓòÉΓòÉ

Whether a title bar is provided:

0         No title bar
1         Title bar provided

Default: 1 (Title bar provided)


ΓòÉΓòÉΓòÉ 218.1.36. VISIBLE ΓòÉΓòÉΓòÉ

Whether the window is displayed or hidden:

0         Window not displayed
1         Window displayed

Default: 1 (Displayed)

A window which is already visible when its VISIBLE attribute is set to 1 is
made the active window.


ΓòÉΓòÉΓòÉ 218.1.37. VSCRLBAR ΓòÉΓòÉΓòÉ

Whether a vertical scroll bar is included:

0         No scroll bar
1         Scroll bar

Default: 0 (No scroll bar)


ΓòÉΓòÉΓòÉ 218.1.38. VSCRLBARPOSN ΓòÉΓòÉΓòÉ

Position of vertical scroll bar slider. Integer in the range 1-1000.

Default: 1 (Top)


ΓòÉΓòÉΓòÉ 218.1.39. VTHUMBSIZE ΓòÉΓòÉΓòÉ

Size of the vertical scroll bar thumb. Integer in the range 1-1000.

Can be modified but not queried.

Default: Calculated by Visualizer.


ΓòÉΓòÉΓòÉ 218.1.40. WIDTH ΓòÉΓòÉΓòÉ

Width of the window, in millimeters.

Once the window is opened, the value is read-only.

Default: Calculated by Visualizer.


ΓòÉΓòÉΓòÉ 218.1.41. X ΓòÉΓòÉΓòÉ

Horizontal position of window on the screen, in pixels.

Default: Calculated by Visualizer.


ΓòÉΓòÉΓòÉ 218.1.42. Y ΓòÉΓòÉΓòÉ

Vertical position of window on the screen, in pixels.

Default: Calculated by Visualizer.


ΓòÉΓòÉΓòÉ 218.2. Actions ΓòÉΓòÉΓòÉ

FLUSH()                 MAX()
MIN()                   NORM()
PRINT()                 REFRESH()
SETORDER()              QUERYORDER()


ΓòÉΓòÉΓòÉ 218.2.1. FLUSH() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇFLUSH()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

If a data entry field on this window has cursor focus, this action forces it to
write its contents immediately to the variable or table it relates to.


ΓòÉΓòÉΓòÉ 218.2.2. MAX() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇMAX()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Maximizes the window to full size as defined by MAXX and MAXY.


ΓòÉΓòÉΓòÉ 218.2.3. MIN() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇMIN()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Minimizes the window to an icon.


ΓòÉΓòÉΓòÉ 218.2.4. NORM() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇNORM()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Restores the window to its normal size as defined by SIZEX and SIZEY.


ΓòÉΓòÉΓòÉ 218.2.5. PRINT() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇPRINT(printer,sizex,sizey,posx,posy,c_area)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

printer is the object handle of an open PRINTER object.

sizex and sizey are the dimensions for the window on the paper. The units used
are 1% of the paper size.

posx and posy give the position of the bottom left-hand corner of the window on
the paper.

c_area controls printing of the window frame. If set to 0 only the client area
is printed, if 1 the window frame is also printed.  If not specified, the
default is 1.

The units used are 1% of the paper size.  If size and position are not
specified, the object is forced to uniform aspect ratio on the printed image.


ΓòÉΓòÉΓòÉ 218.2.6. REFRESH() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇREFRESH()ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Immediately updates all controls in the window to display the underlying data.
(Normally, the system only updates the screen display when a wait state is
reached.)

Specific boxes can also be refreshed by using the REFRESH() action for that
box.


ΓòÉΓòÉΓòÉ 218.2.7. SETORDER() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇSETORDER(tabvec)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Sets the tab order of controls in the window. This is the order in which focus
changes when the user presses the Tab key.

tabvec is a vector of pointers to object handles of controls on the window, in
the required order. For a clone set, include only one pointer. Do not include
pointers to objects that cannot receive focus, (for example, TEXT controls).

The tab order is cyclic-when focus is on the last control and the user presses
the Tab key, then focus passes to the first control. If tabvec does not include
pointers to all the controls in the window, then the controls that you omit
follow the last control in tabvec, with their order unchanged.

SETORDER() returns the number of valid pointers processed. If the action is
successful, then this equals  tabvec[0]'ENTRIES. If any pointer is not valid,
then SETORDER() signals a Display Manager error and ignores that pointer.


ΓòÉΓòÉΓòÉ 218.2.8. QUERYORDER() ΓòÉΓòÉΓòÉ

ΓöÇΓöÇQUERYORDER(tabvec)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ

Queries the tab order of controls in the window. This is the order in which
focus changes when the user presses the Tab key.

QUERYORDER() fills the vector tabvec with pointers to object handles of
controls on the window, in the tab order. The tab order is cyclic-when focus is
on the last control and the user presses the Tab key, then focus passes to the
first control.

QUERYORDER() returns the number of pointers written. If the vector was created
by DECLARE, then it's size cannot be increased, so it might not be able to
contain all the pointers. If tabvec is a newly defined data manager vector,
then the returned value equals  tabvec[0]'ENTRIES.

tabvec does not include pointers to objects that do not receive focus, for
example TEXT controls. tabvec includes only one pointer to each clone set.

To obtain the three-part data manager names for the object handle variables,
convert each pointer into a string.


ΓòÉΓòÉΓòÉ 218.3. Events ΓòÉΓòÉΓòÉ

DESKTOP                    DISCARD
ENTER                      ESCAPE
PRINT(pPrinter)            QUIT
SCHEME                     SCROLL
SELECT


ΓòÉΓòÉΓòÉ 218.3.1. DESKTOP ΓòÉΓòÉΓòÉ

Signaled when the window is resized, minimized, or maximized or when an
extended selection of controls on the window is confirmed. A.System.Operation
is set to one of "MIN", "MAX", "NORM", "SIZE", or "AUTOSELECT". If the
operation is "AUTOSELECT" (extended selection), then A.System.Object is set to
the name of the control with solid sizing handles.


ΓòÉΓòÉΓòÉ 218.3.2. DISCARD ΓòÉΓòÉΓòÉ

Signaled when the mini-icon is dropped on the shredder. (See also the
SOURCECTRL object.)


ΓòÉΓòÉΓòÉ 218.3.3. ENTER ΓòÉΓòÉΓòÉ

Signaled when the ENTER key is pressed while cursor focus is on this window.


ΓòÉΓòÉΓòÉ 218.3.4. ESCAPE ΓòÉΓòÉΓòÉ

Signaled when the ESCAPE key is pressed while cursor focus is on this window.


ΓòÉΓòÉΓòÉ 218.3.5. PRINT(pPrinter) ΓòÉΓòÉΓòÉ

Signaled when the mini-icon is dropped on a printer object. (See also the
SOURCECTRL object.)


ΓòÉΓòÉΓòÉ 218.3.6. QUIT ΓòÉΓòÉΓòÉ

Signaled when the system icon signals CLOSE.


ΓòÉΓòÉΓòÉ 218.3.7. SCHEME ΓòÉΓòÉΓòÉ

Signaled when a font from the OS/2 font palette is dropped on the window.
A.System.Operation is set to "FONT". A.System.BoxValue is set to the OS/2 font
string.


ΓòÉΓòÉΓòÉ 218.3.8. SCROLL ΓòÉΓòÉΓòÉ

Signaled when scroll bars are moved.


ΓòÉΓòÉΓòÉ 218.3.9. SELECT ΓòÉΓòÉΓòÉ

Signaled when the window background is selected.


ΓòÉΓòÉΓòÉ 218.4. Examples ΓòÉΓòÉΓòÉ

A window can be opened statically or dynamically.  Static opening uses a window
created previously, and stored in the same application as a model for the new
window, while dynamic opening defines the window characteristics at runtime.

! You can specify the size when opening a window dynamically.
OPEN WINDOW MyWin,
 SizeX = 300,
 SizeY = 200
...
! You can change the size of the window at any point in the application.
LET MyWin'SizeX = 500

! And you can group changes into a single statement.
MODIFY MyWin,
  SizeX = 230 + BorderWidth,
  SizeY = 120 + BorderHeight,
  Title = "Title of my re-sized window"

A window stored as the file STOREWIN.WIN would be compiled into the windows
group in an application (compilation removes the filename extension). A program
in the same application could open the window with:

OPEN WINDOW T..MyWin, ,"I.windows.STOREWIN"
! This statement is generated automatically when code generation
! is done using the program editor.

The read-only attributes WIDTH and HEIGHT can be queried to return the physical
width and height in millimeters of the client area of the window.

OPEN WINDOW Window,                  ! Open a window setting     !
  SIZEX    = 60,                     !  its width and height in  !
  SIZEY    = 30                      !  dialog units.            !
LET Width  = Window'WIDTH            ! Get the window width and  !
LET Height = Window'HEIGHT           !  height in millimeters.   !

!
! Sample code to dynamically open a window.
PROCEDURE WINDOW
DO
  !
  ! mandatory attributes are sizex and sizey
  OPEN WINDOW SampWind,
   SizeX      = 200,
   SizeY      = 200,
   Border     = 0,                ! normal sizing border
   MinMax     = 0,                ! Min/Max icon on window (default on)
   SysMenu    = 1,                ! System menu (default on)
   Title      = "Dynamic objects",! Window title (default "")
   Visible    = 1,                ! window opened visible (default)
   Selectable = 0,                ! client area of window does not
                                  !  return SELECT Events.

   !
   ! the following attributes will include both horizontal and
   ! vertical scroll bars on the window (default - no scroll bars)
   HScrlBar       = 1,
   VScrlBar       = 1,
   HScrlBarPosn   = 1000,
   HThumbSize     = 500,
   VScrlBarPosn   = 1000,
   VThumbSize     = 500,
   !
   ! these attributes control the maximum and minimum size to which
   ! the window may be sized using the sizing border
   ! (default - no max or min)
   MinX           = 50,
   MinY           = 100,
   MaxX           = 200,
   MaxY           = 200,
   !
   ! A modal window will suspend activity on any other window
   ! within the application until the modal window is closed
   Modal          = 0
END

The following code opens a window, then queries the tab order:

OPEN WINDOW MyWin, ...
OPEN PUSH MyPsh1, MyWin, ...
OPEN SLE MySle1, MyWin, CLONES=5, ...
OPEN LIST MyList1, MyWin, ...

DEFINE TabOrder[0]
DO i = 1 : MyWin'QUERYORDER(TabOrder)
  ERROR 0, "Item _ in the tab order is: ^", i, TabOrder[i]
END

This produces the following output:

Item 1 in the tab order is "T..MyPsh1"
Item 2 in the tab order is "T..MySle1"
Item 3 in the tab order is "T..MyList1"

The following code sets the tab order, then queries it again.

DEFINE NewTabOrder[0]
INSERT NewTabOrder[0] = POINTER(MyList1[0])
INSERT NewTabOrder[0] = POINTER(MySle1[0])
CALL MyWin'SETORDER(NewTabOrder[0])

DEFINE TabOrder2[0]
DO i = 1 : MyWin'QUERYORDER(TabOrder2)
  ERROR 0, "Item _ in the tab order is: ^", i, TabOrder2[i]
END

This produces the following output:

Item 1 in the tab order is "T..MyList1"
Item 2 in the tab order is "T..MySle1"
Item 3 in the tab order is "T..MyPsh1"

Examples source library:


ΓòÉΓòÉΓòÉ 219. WORDPOS() ΓòÉΓòÉΓòÉ

The WORDPOS() function returns the position of the word, at character position
n The words are counted from left to right, and the first word in the string
equals 1.

                           ΓöîΓöÇ" "ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöÇΓöÇWORDPOS(string,number,ΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                           ΓööΓöÇseparatorΓöÇΓöÿ

Examples

More about WORDPOS()

See also: CWORDPOS()


ΓòÉΓòÉΓòÉ 219.1. Examples ΓòÉΓòÉΓòÉ

The following statement:

DECLARE NUMERIC x
LET x = WORDPOS('Jane.Alex.Roger', 9, '.')

returns 2, because the ninth character is in the second word in the string when
"." is being used as a separator (separators count when counting the character
positions).

Examples source library:


ΓòÉΓòÉΓòÉ 219.2. More about WORDPOS() ΓòÉΓòÉΓòÉ

o A zero-length string or a string which contains nothing but separators,
  returns zero.

o If there are fewer than number characters in string, the function returns
  zero.

o Automatic conversion of parameters is carried out if necessary.

o An error is returned if number is negative or NULL. Real numbers are
  truncated.

o A string parameter of type NULL in this function produces a result of NULL.

o In this function, a word is defined by a combination of separators (the
  default is space), string start, and string end. No lexical, syntactic, or
  semantic analysis is implied.

o Any separator parameter used must be a string exactly one character in
  length.  No DBCS characters can be used. However, when an SBCS space is
  specified as separator, both SBCS and DBCS spaces in the string are assumed
  to be spaces.

o In an SBCS environment, WORDPOS() and CWORDPOS() always return the same
  value. In the following example, if ╨┤ is a DBCS character:

    LET x = WORDPOS("ja╨┤e.alex.roger", 6, ".")

  returns 1, but CWORDPOS() would return 2.


ΓòÉΓòÉΓòÉ 220. WORDS() ΓòÉΓòÉΓòÉ

The WORDS() function returns the number of words in a string, or a specified
word or phrase in a string.

                               ΓöîΓöÇ" "ΓöÇΓöÉ
ΓöÇΓöÇWORDS(string,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ,ΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇ,ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
                  ΓööΓöÇnumberΓöÇΓöÿ   ΓööΓöÇsepΓöÇΓöÿ   ΓööΓöÇlengthΓöÇΓöÿ

Examples

More about WORDS()

See also: COUNT(), SEPARATE()


ΓòÉΓòÉΓòÉ 220.1. Examples ΓòÉΓòÉΓòÉ

word_count     = WORDS("How many cows came home?")
                             ! word_count is 5
third_position = WORDS("How many cows came home?", 3 )
                             ! third_position is "cows"
barn_position  = WORDS("cow-in-a-barn", 4, "-" )
                             ! barn_position is "barn"
no_number      = WORDS("cow", , "*" )
                             ! no_number is 1
spaced_str     = WORDS("* cow * ", 1, "*" )
                             ! spaced_str is " cow "
phrase         = WORDS("How many cows came home?", 2, , 3 )
                             ! phrase is "many cows came"

Examples source library:


ΓòÉΓòÉΓòÉ 220.2. More about WORDS() ΓòÉΓòÉΓòÉ

o If one parameter is supplied, the WORDS() function returns the number of
  words in the string.  A zero-length string or one containing only separators
  return zero.

o If two parameters are supplied, the WORDS() function returns a string
  containing word number number from string. If the value of number exceeds the
  number of words in string, the function returns a string of length zero.

o Only SBCS characters should be used as separators.  However, if the separator
  character used is a space, a DBCS space in string is treated in the same way
  as an SBCS space.

o Automatic conversion of parameters is carried out if necessary.

o An error is returned if number is NULL. Real numbers are truncated. If a
  negative number is supplied, the count begins at the end of the string (the
  last word is -1) and goes backwards to the start.

o Using a string parameter of type NULL in this function produces a result of
  NULL.

o For the WORDS() function, a word is defined by a combination of separators
  (the default is space), string start, and string end. No lexical, syntactic,
  or semantic analysis is implied.

In a DBCS environment:

o Only SBCS characters can be used as separators. When an SBCS space is used as
  a separator, or

o Only SBCS characters can be used as separators. When an SBCS space is used as
  a separator, or separator is omitted, SBCS and DBCS spaces in string are both
  assumed to be spaces.


ΓòÉΓòÉΓòÉ 221. Standard graphics attributes ΓòÉΓòÉΓòÉ

Many graphics objects have the following attributes:

BOUNDED           Whether a line is drawn around the object:

   0  No line
   1  Line

                  Default: 1 (Boundary line)

COLOR             Integer in the range 1-19. See  for details of colors
                  available.

                  Default: 0

CONSTANT          Whether the values in the reference vector are read into
                  memory at the time the primitive is opened, or are read each
                  time the graphic box is repainted.

   0  Reference vector values are read each time the box is repainted
   1  Reference vector values are read and stored when the primitive is opened.

                  Set on OPEN, then cannot be queried.

                  Default: 1 (Values stored)

DRAGABLE          Whether objects in the graphic area can be dragged:

   0  Objects cannot be dragged
   1  Objects can be dragged

                  Default: 0 (Cannot be dragged)

FILLCOLOR         Integer in the range 1-19. See  for details of colors
                  available.

                  Default: 0

FILLPATTERN       Integer in the range 0-15. See  for details of patterns
                  available.

                  Default: 0

LINESTYLE         Style of the line.  Styles range from 0-10:

   0     Solid
   2-6   Various dashed and dotted lines
   7     Solid
   8     Invisible

         Default: 0 (Solid)

LINEWIDTH         Width of the line, in pixels.

                  Default: 1 pixel

MIX               How the color of a primitive is combined with the color of
                  any underlying primitive.

   0  Overpaint-no underlying color shows through
   1  Leavealone-underlying color shows through
   2  XOR-colors of the primitive and the background are combined
      electronically in an exclusive OR logical relationship
   3  Allows pattern mixing (the white area of the pattern is transparent and
      allows patterns below it to be seen).

                  Default: 0 (Overpaint)

ORIGIN            The corner of the enclosing window to be taken as the origin.
                  The position of the object is measured from this point.

   "TL"  Top left
   "TR"  Top right
   "BL"  Bottom left
   "BR"  Bottom right

                  Default: "BL" (Bottom left)

SELECTABLE        Whether an object is selectable or not. When a selectable
                  object is selected by the user, a SELECT event is signaled to
                  the object handler:

   0  Object not selectable
   1  Object selectable

                  Default: 1 (Selectable)

SELECTED          Whether an object is highlighted with a border when selected:

   0  Object not highlighted
   1  Object highlighted

                  Default: 0 (Not highlighted)

VISIBLE           Whether the item is visible or not. Objects that are not
                  visible are present on the screen, but they are displayed in
                  colors which make them invisible against their background.

   0  Object not visible
   1  Object visible

                  Default: 1 (Visible)

X                 Horizontal position within the window, in dialog box units.

                  Default: 0

Y                 Vertical position within the window, in dialog box units.

                  Default: 0


ΓòÉΓòÉΓòÉ 222. Attributes, actions, and events ΓòÉΓòÉΓòÉ

This appendix lists the events that objects signal, the attributes of objects,
and the actions of objects.

The use of these may vary between different objects. For further details of any
event, attribute, or action, see the entry for the object in the reference
section.)

Dictionary attributes for variables are listed separately in .

The suffix √ denotes a standard graphic attribute. See  for more information on
these.

Attributes

Actions

Events


ΓòÉΓòÉΓòÉ 222.1. Attributes ΓòÉΓòÉΓòÉ

Attribute               Objects

ACCESS                  DATATRANS FILE

ACTIVE                  LINK

ALIGNMENT               STRING

ANCHORX                 ENTRY

ANCHORY                 ENTRY

ANGLE                   STRING

APPLICATION             DDECLIENT DDESERVER LINK REFERENCE

ASCODE                  AS

ASPECTRATIO             GRAPHIC

ASYNCHRONOUS            MMFILE

AUTOCOMMIT              DATASESSION

AUTOREFRESH             ENTRY IBMCHART IBMREPORT LIST

AUTORESTART             LINK

AUTOSCROLL              SLE

AUTOSELECT              WINDOW

AUTOTAB                 SLE

BGCOLOR                 BITMAP ENTRY FOLDERVIEW GRAPHIC LIST PROFILE RADIO TEXT
                        WINDOW

BITMAP                  BITMAP PUSH

BORDER                  ENTRY LIST SLE WINDOW

BOUNDED √               ARC ARCPOINTS AREA CIRCLE CURVE ELLIPSE LINE OUTLINE
                        POLYGON RECTANGLE SECTOR

BUTTONTITLE             FILEDLG

CDIR                    SYSTEM

CDRIVE                  SYSTEM

CELLX                   POINT STRING

CELLY                   POINT STRING

CHECKED                 CHECK RADIO VALUE

CLASSNAME               BITMAP

CLIENTS                 DDESERVER

CLIPMAXX                DEFINE

CLIPMAXY                DEFINE

CLIPMINX                DEFINE

CLIPMINY                DEFINE

CLONEDIR                CHECK ENTRY PUSH RADIO SLE TEXT

CLONEGAP                CHECK ENTRY PUSH RADIO SLE TEXT

CLONES                  CHECK ENTRY PUSH RADIO SLE TEXT

CLOSINGLINE             ARC ARCPOINTS AREA CURVE LINE OUTLINE

CODE                    AS AS400SESSION AS400TRANS DATASESSION DATATRANS
                        DDECLIENT DDESERVER FILE FILEDLG FOLDER FOLDERITEM
                        HLLAPI IBMAPPLICATN IBMCHART IBMDATA IBMREPORT
                        IBMSQLSTATEMENT IBMSQLTABLE IBMTABLE LINK MAIL MMFILE
                        OBJECTSTORE PRINTER SOURCECTRL SQLSESSION SQLTRANS
                        STREAM SYSTEM TABLE TARGETCTRL VIEWORDER

CODEDETAIL              AS AS400SESSION AS400TRANS DATASESSION DATATRANS
                        SQLSESSION SQLTRANS

CODEPAGE                PROFILE

CODEPAGETYPE            PROFILE

COLNAMES                IBMSQLTABLE

COLOR                   PRINTER

COLOR √                 ARC ARCPOINTS AREA CIRCLE CURVE DEFINE ELLIPSE LINE
                        OBJECT OUTLINE POINT POLYGON RECTANGLE SECTOR STRING

COLS                    VALUE

COLTITLE                LIST

COLTITLE1               LIST

COLTITLE2               LIST

COLUMNS                 AS DATATRANS LIST TABLE

COMMENT                 OBJECTSTORE TABLE

CONFIRM                 IBMSQLSTATEMENT

CONNECT                 DATASESSION

CONSTANT √              ARC ARCPOINTS CIRCLE CURVE ELLIPSE LINE OUTLINE POINT
                        POLYGON RECTANGLE SECTOR STRING

CONTAINERNAME           TARGETCTRL

CONVERT                 FILE

COPIES                  PRINTER

CURRENCY                PROFILE

CURSORBOX               WINDOW

CURSORCLONE             WINDOW

CURSORPOS               HLLAPI

CURSORX                 ENTRY LIST

CURSORY                 ENTRY LIST

DATA                    VIEWCALCS VIEWORDER VIEWROWS VIEWTABLES

DATABASE                IBMSQLTABLE

DATAEVENT               LIST

DATATYPE                IBMSQLTABLE

DATE                    PROFILE

DATEFORMAT              PROFILE

DATEMETHOD              AS

DATESEPAR               PROFILE

DBCSFONT                PROFILE

DBNAME                  DATASESSION IBMSQLSTATEMENT SQLSESSION

DECSEPAR                PROFILE

DEFAULT                 PUSH

DEFAULT.                RECTANGLE

DEFAULTFORMAT           LINK

DEFINE                  OBJECT

DESCRIPTION             PRINTER

DETAIL                  FOLDERITEM

DETAILHEADINGTEXT       FOLDER

DETAILHEADINGVISIBLE    FOLDERVIEW

DETAILVISIBLE           FOLDERVIEW

DIALOG                  IBMAPPLICATN IBMCHART IBMDATA IBMREPORT IBMSQLSTATEMENT
                        IBMTABLE LINK PRINTER

DIRECTION               SCROLL STRING

DIRLISTTXT              FILEDLG

DISABLED                TBAR

DISCARDABLE             SOURCECTRL

DLL                     PRESSPACE

DOWN                    TBAR

DRAGABLE                BITMAP DEFINE GRAPHIC

DRAGBORDER              DEFINE

DRIVE                   SQLSESSION

DRIVELISTTXT            FILEDLG

DSSDIR                  PROFILE

DSSPATH                 PROFILE

EA                      FILEDLG

EDITABLE                FOLDER FOLDERITEM

ENABLED                 CHECK DROPENTRY DROPLIST LIST PUSH RADIO SCROLL SLE
                        TEXT VALUE

ENCLOSED                ARC ARCPOINTS AREA CURVE LINE OUTLINE

END                     AREA

EOF                     AS400TRANS DATATRANS FILE SQLTRANS

ERASE                   REFERENCE

ERRORINFO               AS

EUIMODE                 IBMCHART IBMREPORT

EXCLUSIVE               MMFILE

EXE                     PROFILE

EXPRESSION              CHECK DROPENTRY DROPLIST ENTRY GRAPHIC GROUP LIST PUSH
                        RADIO SLE TEXT

FGCOLOR                 BITMAP ENTRY FOLDERVIEW GRAPHIC LIST PROFILE RADIO TEXT
                        WINDOW

FILELISTTXT             FILEDLG

FILENAMETXT             FILEDLG

FILINGSYSTEM            IBMDATA

FILLCOLOR √             ARC ARCPOINTS AREA CIRCLE CURVE DEFINE ELLIPSE LINE
                        OBJECT OUTLINE POLYGON RECTANGLE SECTOR

FILLPATTERN √           ARC ARCPOINTS AREA CIRCLE CURVE DEFINE ELLIPSE LINE
                        OBJECT OUTLINE POLYGON RECTANGLE SECTOR

FILTERLISTTXT           FILEDLG

FIRSTCHAR               ENTRY SLE

FIXEDCOLS               LIST

FIXEDFONT               ENTRY

FIXEDROWS               LIST

FOLDER                  FOLDERITEM

FOLDERITEM              FOLDER

FONT                    LIST STRING WINDOW

FONTFIXED               LIST

FONTTITLE               LIST

FORMAT                  FILE STREAM

FORMATS                 COPYTO SEND

GENKEYCOL               AS400TRANS DATATRANS SQLTRANS

GRIDX                   WINDOW

GRIDY                   WINDOW

GROUP                   TBAR

HANDLES                 CHECK DROPENTRY DROPLIST ENTRY GRAPHIC GROUP LIST PUSH
                        RADIO SCROLL SLE TEXT VALUE

HEADINGTEXT             FOLDER

HEADINGVISIBLE          FOLDERVIEW

HEIGHT                  GRAPHIC PRINTER WINDOW

HELP                    CHECK COPYTO DROPENTRY DROPLIST ENTRY FILEDLG
                        FOLDERITEM GRAPHIC GROUP LIST PUSH RADIO SCROLL SEND
                        SLE TBAR TEXT VALUE WINDOW

HELPBUTTON              PUSH

HELPFORHELP             HELP

HELPGLOBAL              TBAR

HELPIDS                 TBAR

HELPTITLE               FILEDLG

HILITEBGCOLOR           PROFILE

HILITEFGCOLOR           PROFILE

HORZJUST                SLE STRING TEXT

HORZSCROLL              ENTRY LIST

HOSTCODEPAGE            AS

HOSTMESSAGE             AS

HOSTMSGNO               AS

HOT                     LINK

HSCRLBAR                WINDOW

HSCRLBARPOSN            WINDOW

HTHUMBSIZE              WINDOW

HYPERTEXTID             HELP

IBMDATA                 IBMCHART

ICON                    FOLDERITEM WINDOW

ID                      BITMAP LINK

IDENTIFIER              COPYTO FILEDLG IBMAPPLICATN IBMCHART IBMREPORT
                        IBMSQLSTATEMENT IBMTABLE SEND

INFOAREA                IBMTABLE

INISTATE                TBAR

INSTANCE                PROFILE

INTERFACE               DATASESSION

ITEM                    COPYTO DDECLIENT LINK REFERENCE

ITEMLIST                VALUE

ITEMTYPE                VALUE

KEEP                    TABLE

KEYED                   AS TABLE

KEYS                    AS HELP TABLE

LANGUAGE                PROFILE

LATCH                   TBAR

LEFTCOL                 LIST

LENGTH                  FILE MMFILE

LIBNAME                 FILEDLG HELP

LINESPACING             FOLDERVIEW

LINESTYLE √             ARC ARCPOINTS AREA CIRCLE CURVE DEFINE ELLIPSE LINE
                        OBJECT OUTLINE POLYGON RECTANGLE SECTOR

LINEWIDTH √             ARC ARCPOINTS AREA CIRCLE CURVE DEFINE ELLIPSE LINE
                        OBJECT OUTLINE POLYGON RECTANGLE SECTOR

LINK                    STREAM

LINKS                   LINKSHOW

LISTREF                 DROPENTRY DROPLIST

LISTTYPES               VIEWTABLES

LOCATION                FILE FILEDLG LINK MMFILE OBJECTSTORE REFERENCE STREAM
                        TABLE

MAIL                    PROFILE

MAXCLIENTS              DDESERVER

MAXX                    WINDOW

MAXY                    WINDOW

MENUREF                 FOLDERVIEW WINDOW

METAFILE                VIEWPORT

MINMAX                  WINDOW

MINX                    WINDOW

MINY                    WINDOW

MIX √                   ARC ARCPOINTS AREA BITMAP CIRCLE CURVE ELLIPSE LINE
                        OBJECT OUTLINE POINT POLYGON RECTANGLE SECTOR STRING

MODAL                   VIEWCALCS VIEWORDER VIEWROWS VIEWTABLES WINDOW

MODE                    AS400TRANS ENTRY FILE OBJECTSTORE SQLTRANS STREAM TABLE

MODIFIED                IBMCHART IBMDATA IBMREPORT IBMSQLSTATEMENT IBMTABLE

MODRECS                 DATASESSION

MOVEX                   DEFINE OBJECT

MOVEY                   DEFINE OBJECT

MULTILINE               STRING

NAME                    AS FILE FILEDLG FOLDERITEM IBMAPPLICATN IBMCHART
                        IBMREPORT IBMSQLSTATEMENT IBMTABLE LINK MMFILE
                        OBJECTSTORE REFERENCE STREAM TABLE

NAMEHEADINGTEXT         FOLDER

NAMEVISIBLE             FOLDERVIEW

NATIVEFORMAT            LINK

OBJECTCLASS             TABLE

OBJECTNAME              COPYTO LINK LINKSHOW SEND SOURCECTRL STREAM

OBJECTVIEW              WINDOW

OL_ALL                  TEXT

OL_COLOR                TEXT

OL_DETAIL               TEXT

OL_LEFT                 TEXT

OL_OVER                 TEXT

OL_RIGHT                TEXT

OL_UNDER                TEXT

OPENED                  FOLDERITEM

OPERATION               SOURCECTRL TARGETCTRL

OPERATIONS              SOURCECTRL

ORDERDATA               LIST

ORDERSIGNS              VIEWORDER

ORDERVECTOR             VIEWORDER

ORIGIN                  CHECK DROPENTRY DROPLIST ENTRY GRAPHIC GROUP LIST
                        MMFILE PRESSPACE PUSH RADIO SCROLL SLE TEXT VALUE

ORIGINATOR              PRINTER SOURCECTRL STREAM TARGETCTRL

ORIGINX                 DEFINE ENTRY OBJECT

ORIGINY                 DEFINE ENTRY OBJECT

OVERFLOW                TEXT

OWNER                   CLIPBOARD

OWNERWINDOW             COPYTO LINKSHOW SEND VIEWCALCS VIEWORDER VIEWROWS
                        VIEWTABLES WINDOW

PATH                    IBMDATA

PATTERN                 GRAPHIC WINDOW

PCS                     PROFILE

PERCENTAGE              IBMCHART

PERSPECTIVE             IBMCHART

PLACES                  PROFILE

PLATFORM                SQLSESSION

POINT                   FILE STREAM

POPUPMENUREF            FOLDERITEM

POSITION                MMFILE

PREFIX                  OBJECTSTORE TABLE

PRINTABLE               SOURCECTRL

PROCLINE                AS

PROCNAME                AS PRESSPACE

PROTECT                 SLE

RANGEEND                SCROLL

RANGESTART              SCROLL

READONLY                IBMSQLSTATEMENT IBMTABLE MMFILE

REASON                  DATASESSION DATATRANS IBMAPPLICATN IBMCHART IBMDATA
                        IBMREPORT IBMSQLTABLE IBMTABLE MMFILE

REFERENCE               ARC ARCPOINTS CIRCLE CURVE ELLIPSE LINE LIST OUTLINE
                        POINT POLYGON RECTANGLE SECTOR STREAM STRING

RELATIONAL              PROFILE

RELOBJECT               AS

REPLACE                 PROFILE

RESOURCE                BITMAP FOLDERITEM VALUE

RESTARTABLE             LINK

RETURNCODE              SYSTEM

ROTATE                  DEFINE OBJECT

ROTATED                 IBMCHART

ROTATEX                 DEFINE OBJECT

ROTATEY                 DEFINE OBJECT

ROWS                    LIST TABLE VALUE

RUN                     PROFILE

SAVEPROMPT              IBMCHART IBMREPORT

SCALE                   VALUE

SCALED                  PUSH

SCALEX                  DEFINE OBJECT

SCALEY                  DEFINE OBJECT

SCROLLEVENT             LIST

SELECT                  AS

SELECTABLE              ENTRY GRAPHIC SLE TEXT WINDOW

SELECTABLE √            ARC ARCPOINTS AREA BITMAP CIRCLE CURVE DEFINE ELLIPSE
                        LINE OBJECT OUTLINE POINT POLYGON RECTANGLE SECTOR
                        STRING

SELECTCELLS             LIST

SELECTCOLS              LIST

SELECTED √              ARC ARCPOINTS AREA BITMAP CIRCLE CURVE DEFINE ELLIPSE
                        LINE OBJECT OUTLINE POINT POLYGON RECTANGLE SECTOR
                        STRING

SELECTION               FOLDERVIEW LIST

SELECTMODE              LIST

SELECTROWS              LIST

SERVERNAME              AS

SERVERTYPE              AS

SESSION                 HLLAPI

SHEAR                   STRING

SHORTDATE               PROFILE

SIZE                    STREAM STRING

SIZEX                   BITMAP CHECK DROPENTRY DROPLIST ENTRY FOLDERVIEW
                        GRAPHIC GROUP LIST MMFILE PRESSPACE PUSH RADIO SCROLL
                        SLE TEXT VALUE VIEWPORT WINDOW

SIZEY                   BITMAP CHECK DROPENTRY DROPLIST ENTRY FOLDERVIEW
                        GRAPHIC GROUP LIST MMFILE PRESSPACE PUSH RADIO SCROLL
                        TBAR TEXT VALUE VIEWPORT WINDOW

SKIPREFRESH             GRAPHIC

SLIDERPOS               SCROLL

SOURCECTRL              FOLDERVIEW WINDOW

SOURCENAME              TARGETCTRL

SOURCETYPE              REFERENCE

SQLSTATE                SQLSESSION SQLTRANS

SQLSTRING               IBMSQLTABLE

SQLTABLE                IBMSQLTABLE

SRPI                    PROFILE

STARTCOMMAND            LINK

STATUS                  MMFILE SQLSESSION STREAM

STYLE                   POINT

SYSMENU                 WINDOW

SYSTEM                  AS400SESSION

TABACTION               ENTRY

TABLE                   AS400TRANS DATATRANS IBMDATA SQLTRANS VIEWORDER

TAGSTYLE                LIST

TARGETCTRL              FOLDERVIEW WINDOW

TARGETX                 FOLDERVIEW WINDOW

TARGETY                 FOLDERVIEW WINDOW

TEMPLOCATION            REFERENCE

TEMPNAME                REFERENCE

TEXT                    CHECK GROUP PUSH RADIO TEXT

TEXTLIMIT               DROPENTRY ENTRY SLE

THOUSEPAR               PROFILE

THUMBSIZE               SCROLL

TILT                    ARC ARCPOINTS ELLIPSE SECTOR

TIME                    PROFILE

TIMEFORMAT              MMFILE PROFILE

TIMEOUT                 AS DDECLIENT MMFILE

TIMESEPAR               PROFILE

TITLE                   FILEDLG VIEWORDER VIEWTABLES WINDOW

TITLEBAR                WINDOW

TITLEINFO               LIST

TOGGLE                  TBAR

TOOLDATA                TBAR

TOOLTEXT                TBAR

TOPIC                   DDECLIENT DDESERVER LINK REFERENCE

TOPROW                  LIST

TRACE                   DDECLIENT DDESERVER SOURCECTRL TARGETCTRL

TRACEAS                 AS

TRACELEVEL              AS400SESSION DATASESSION MMFILE SQLSESSION

TRACEPC                 AS

TRACESERVER             AS

TREELINEVISIBLE         FOLDERVIEW

TREEVIEWINDENT          FOLDERVIEW

TRIM                    DATATRANS

TYPE                    AS FOLDERITEM IBMCHART STREAM TABLE

TYPEHEADINGTEXT         FOLDER

TYPEVISIBLE             FOLDERVIEW

UNIFORM                 VIEWPORT

UP                      TBAR

USERID                  SQLSESSION

VALUE                   DROPENTRY DROPLIST

VERSION                 DATASESSION PROFILE

VERTJUST                TEXT

VERTSCROLL              ENTRY LIST

VIEW                    FOLDERVIEW IBMTABLE

VISIBLE                 CHECK COPYTO DROPENTRY DROPLIST ENTRY FOLDERITEM
                        GRAPHIC GROUP LINKSHOW LIST MMFILE PRESSPACE PUSH RADIO
                        SCROLL SEND SLE TBAR TEXT VALUE VIEWORDER WINDOW

VISIBLE √               ARC ARCPOINTS AREA BITMAP CIRCLE CURVE DEFINE ELLIPSE
                        LINE OBJECT OUTLINE POINT POLYGON RECTANGLE SECTOR
                        STRING

VOLUME                  MMFILE

VSCRLBAR                WINDOW

VSCRLBARPOSN            WINDOW

VTHUMBSIZE              WINDOW

WCSMAXX                 GRAPHIC

WCSMAXY                 GRAPHIC

WCSMINX                 GRAPHIC

WCSMINY                 GRAPHIC

WIDTH                   GRAPHIC POINT PRINTER WINDOW

WINDOWSTATUS            HLLAPI

WINDOWTITLE             FOLDERVIEW

WINTITLE                HELP

WORDWRAP                ENTRY TEXT

X                       CHECK DROPENTRY DROPLIST ENTRY FOLDERITEM FOLDERVIEW
                        GRAPHIC GROUP LIST MMFILE PRESSPACE PUSH RADIO SCROLL
                        SLE TEXT VALUE VIEWPORT WINDOW

X √                     BITMAP

XEXTENT                 MMFILE

Y                       CHECK DROPENTRY DROPLIST ENTRY FOLDERITEM FOLDERVIEW
                        GRAPHIC GROUP LIST MMFILE PRESSPACE PUSH RADIO SCROLL
                        SLE TEXT VALUE VIEWPORT WINDOW

Y √                     BITMAP

YEXTENT                 MMFILE


ΓòÉΓòÉΓòÉ 222.2. Actions ΓòÉΓòÉΓòÉ

Action                  Objects

ACTION                  IBMAPPLICATN

ACTIVATE                LINK

ADDFMTEXT               TARGETCTRL

ADDFORMAT               LINK SOURCECTRL TARGETCTRL

ADDLINK                 LINKSHOW

ADDTYPE                 SOURCECTRL TARGETCTRL

ADDTYPEEXT              TARGETCTRL

ADVISE                  DDECLIENT DDESERVER

AFTER                   TIMER

AT                      TIMER

ATTACH                  AS

ATTRIB                  SYSTEM

BITMAP                  GRAPHIC

CALCOLUMNS              AS

CHECK                   LIST

CHECKPOINT              TABLE

CHECKSYNTAX             AS

CLEAR                   GRAPHIC

CLIPBOARD               GRAPHIC

CLOSE                   IBMAPPLICATN IBMSQLSTATEMENT LINK

COLUMNS                 AS DATATRANS IBMDATA IBMTABLE SQLTRANS TABLE

COMMAND                 AS AS400SESSION DATASESSION SQLSESSION SYSTEM

COMMANDCODE             SYSTEM

COMMIT                  DATASESSION SQLSESSION

COMPRESS                IBMTABLE

CONNECT                 HLLAPI

CONTENTS                HELP

CONTRACT                FOLDERVIEW

CONVERTPOS              HLLAPI

COPY                    SYSTEM

COPYEATTRS              FILE OBJECTSTORE

COPYOIA                 HLLAPI

COPYPS                  HLLAPI

COPYTO                  IBMCHART IBMREPORT IBMTABLE MMFILE

CREATE                  LIST SQLTRANS

CREATESVAR              AS

CREATETEMP              AS SYSTEM

CURSORBOX               LIST

DBNAMES                 SQLSESSION

DEACTIVATE              LINK

DELETE                  SYSTEM

DELETESVAR              AS

DELETETEMP              SYSTEM

DELIVER                 CLIPBOARD DDECLIENT

DESTROY                 LIST

DETAILS                 AS

DIRECTORIES             SYSTEM

DISABLE                 VALUE

DISCARD                 IBMAPPLICATN IBMCHART IBMREPORT IBMSQLTABLE IBMTABLE
                        MMFILE

DISCONNECT              HLLAPI

DISMISS                 HELP

DISPLAY                 HELP

DRIVES                  SYSTEM

DROP                    AS

EALIST                  FILEDLG

EDIT                    CHECK DROPENTRY DROPLIST ENTRY GRAPHIC GROUP LIST SLE
                        TEXT VALUE

EMPTY                   CLIPBOARD

ENABLE                  VALUE

EQUALS                  LINK

ERRORTEXT               AS

EXCLUDETEMP             SYSTEM

EXECUTE                 DDECLIENT

EXPAND                  FOLDERVIEW

EXPRESSION              SQLTRANS

FIELDATTR               HLLAPI

FIELDLENGTH             HLLAPI

FIELDPOS                HLLAPI

FIELDTOSTR              HLLAPI

FILE                    SYSTEM

FILES                   SYSTEM

FILTER                  TBAR

FINISHED                STREAM

FLUSH                   WINDOW

FMTEXTS                 TARGETCTRL

FORMATS                 DDESERVER LINK SOURCECTRL TARGETCTRL

GET                     CLIPBOARD FILE LIST

GETASL                  STREAM

GETDATA                 STREAM

GETLINE                 STREAM

GETNEXTROW              AS AS400TRANS DATATRANS SQLTRANS

GETPREVROW              DATATRANS

GETROW                  DATATRANS LIST

GETSQL                  IBMSQLSTATEMENT

GETSVAR                 AS

GETTABLE                AS

GETTITLE                LIST

GOTOTOP                 AS AS400TRANS DATATRANS SQLTRANS

HOTLINK                 LINK

INCLUDETEMP             SYSTEM

INDEX                   HELP

INFO                    IBMDATA

INFORM                  DDESERVER

INQCALCS                IBMDATA

INQCOLPROP              IBMDATA IBMTABLE

INQCOLUMNS              IBMDATA IBMTABLE

INQFIXEDCOLS            IBMTABLE

INQGROUPBY              IBMDATA

INQINFO                 IBMDATA

INQKEYS                 IBMDATA IBMTABLE

INQROWS                 IBMDATA IBMTABLE

INQSUMMARYCALCS         IBMDATA

INQTYPES                IBMDATA IBMTABLE

ITEMS                   DROPENTRY DROPLIST

JOIN                    IBMTABLE

KEYS                    AS DATATRANS SQLTRANS TABLE

LISTCAT                 AS

LOAD                    AS400TRANS DATATRANS IBMDATA LINK REFERENCE SQLTRANS

LOCK                    CLIPBOARD LIST

MAX                     WINDOW

METAFILE                GRAPHIC

MIN                     WINDOW

NOKEYS                  AS TABLE

NORM                    WINDOW

OPEN                    FILEDLG IBMAPPLICATN IBMCHART IBMREPORT IBMSQLSTATEMENT
                        IBMSQLTABLE IBMTABLE

ORDER                   VIEWORDER

PAGESETUP               IBMREPORT

PAUSE                   HLLAPI MMFILE

PLACECURSOR             LIST

PLAY                    MMFILE

POST                    PRESSPACE

PRINT                   GRAPHIC IBMCHART IBMREPORT IBMSQLTABLE IBMTABLE WINDOW

PRINTREQUEST            SYSTEM

PROCESS                 IBMCHART IBMREPORT

PRODUCTCOLUMNS          IBMDATA

PSTOSTRING              HLLAPI

PUT                     CLIPBOARD FILE LIST PRINTER

PUTASL                  STREAM

PUTDATA                 STREAM

PUTLINE                 STREAM

PUTSQL                  IBMSQLSTATEMENT IBMSQLTABLE

PUTSVAR                 AS

PUTTABLE                AS

PUTTITLE                LIST

QUERYADVISES            DDESERVER

QUERYCHECK              LIST

QUERYCLASS              SYSTEM

QUERYCURSOR             LIST

QUERYFORMATS            CLIPBOARD DDECLIENT IBMCHART IBMDATA LINK

QUERYLOCKED             LIST

QUERYORDER              FOLDER WINDOW

QUERYSELECTED           FOLDERVIEW

QUERYTEMP               SYSTEM

QUERYVIEWS              FOLDER

QUERYWIDTH              LIST

RECEIVEFILE             HLLAPI

RECORD                  MMFILE

REFRESH                 CHECK ENTRY GRAPHIC GROUP IBMAPPLICATN IBMSQLSTATEMENT
                        IBMTABLE LIST PUSH RADIO SCROLL SLE TEXT VALUE WINDOW

REFRESHDATA             IBMCHART IBMDATA IBMREPORT

REGISTER                CLIPBOARD

RELEASE                 HLLAPI

RENAME                  SYSTEM

REQUEST                 CLIPBOARD DDECLIENT LINK

RESERVE                 HLLAPI

RESET                   IBMCHART

RESETDATA               IBMCHART

RESETSYSTEM             HLLAPI

RESETTABLE              AS

RESTART                 LINK

RESUME                  MMFILE

ROLLBACK                DATASESSION SQLSESSION

RUN                     IBMSQLSTATEMENT

SAVE                    IBMCHART IBMDATA IBMREPORT IBMSQLSTATEMENT IBMTABLE
                        MMFILE REFERENCE

SAVETO                  FILE IBMAPPLICATN IBMREPORT OBJECTSTORE TABLE

SEARCHFIELD             HLLAPI

SEARCHPATH              SYSTEM

SEARCHPS                HLLAPI

SELANALYSIS             IBMCHART IBMREPORT

SELAREA                 DROPENTRY SLE

SELCOLS                 IBMREPORT

SELDATA                 IBMCHART

SELECT                  AS GRAPHIC

SELECTTABLE             IBMCHART IBMREPORT

SEND                    IBMCHART IBMREPORT IBMTABLE MAIL PRESSPACE SEND

SENDFILE                HLLAPI

SENDKEY                 HLLAPI

SESSIONPARMS            HLLAPI

SESSIONS                HLLAPI

SETAXISTYPE             IBMCHART

SETCALCS                IBMDATA

SETCHECK                LIST

SETCOLFORMAT            IBMREPORT

SETCOLOR                LIST

SETCOLPROP              IBMDATA IBMTABLE

SETCOLTITLE             IBMREPORT

SETCOLUMNS              AS IBMDATA IBMTABLE

SETCOLWIDTH             IBMREPORT

SETCUE                  MMFILE

SETEXPR                 AS400TRANS DATATRANS SQLTRANS

SETFIXEDCOLS            IBMTABLE

SETGROUPBY              IBMDATA

SETIMAGE                SOURCECTRL

SETKEYS                 AS DATATRANS SQLTRANS TABLE

SETOBJECTDATA           SYSTEM

SETORDER                FOLDER WINDOW

SETROWS                 IBMDATA IBMTABLE

SETSELECTED             FOLDERVIEW

SETSUMMARYCALCS         IBMDATA

SETTINGS                PRINTER

SETTITLE                IBMCHART

SETTOPTITLE             IBMREPORT

SETWIDTH                LIST

SETXAXISLAB             IBMCHART

SETYAXISLAB             IBMCHART

SMISEND                 MAIL

SNAPSHOT                AS400TRANS DATATRANS IBMDATA SQLTRANS

SOURCE                  CLIPBOARD

SPLIT                   IBMTABLE

SQLTABLE                DATATRANS

STATE                   TBAR

STATUS                  CLIPBOARD HLLAPI

STOP                    MMFILE

STRINGRECT              GRAPHIC

STRINGTOPS              HLLAPI

STRTOFIELD              HLLAPI

SURFACE                 VIEWCALCS VIEWROWS VIEWTABLES

SYSTEM                  DDECLIENT DDESERVER HLLAPI

TABLENAMES              SQLSESSION

TARGET                  CLIPBOARD

TRANSACTION             DATASESSION

TYPEEXTS                TARGETCTRL

TYPES                   SOURCECTRL TARGETCTRL

UNADVISE                DDECLIENT

UNCHECK                 LIST

UNLOCK                  CLIPBOARD LIST

UPDATE                  LIST

USETMPSOURCE            IBMDATA

VERIFYFORMAT            DDECLIENT LINK


ΓòÉΓòÉΓòÉ 222.3. Events ΓòÉΓòÉΓòÉ

Event                   Objects

ADVISE                  DDESERVER

CONTRACT                FOLDERVIEW

DATA                    DDECLIENT DROPENTRY ENTRY FOLDER FOLDERITEM LIST SLE

DATASELECT              IBMTABLE

DESKTOP                 CHECK DROPENTRY DROPLIST ENTRY FOLDERVIEW GRAPHIC GROUP
                        LIST RADIO SCROLL SLE TEXT VALUE WINDOW

DISCARD                 SOURCECTRL WINDOW

DRAG                    DEFINE GRAPHIC

ENTER                   WINDOW

ERROR                   CLIPBOARD DDECLIENT DDESERVER LINK LINKSHOW SOURCECTRL

ESCAPE                  FOLDERVIEW LIST WINDOW

EXPAND                  FOLDERVIEW

HELP                    HELP LIST

INFORM                  HELP

INITIATE                DDESERVER

LISTDATA                LIST

LISTSCROLL              LIST

OPEN                    DEFINE FOLDER FOLDERITEM GRAPHIC LIST TEXT

ORDER                   VIEWORDER

PRINT                   SOURCECTRL SYSTEM WINDOW

PROFILE                 PROFILE

PROPERTIES              TBAR

QUIT                    COPYTO DDECLIENT FOLDERVIEW IBMCHART IBMREPORT IBMTABLE
                        LINK LINKSHOW MMFILE SEND WINDOW

SCHEME                  WINDOW

SCROLL                  SCROLL WINDOW

SELECT                  CHECK DEFINE DROPLIST GRAPHIC LIST PUSH RADIO SLE TBAR
                        TEXT VALUE WINDOW

SIGNAL                  PRESSPACE

SOURCE                  CLIPBOARD COPYTO DDECLIENT DDESERVER SEND SOURCECTRL

TARGET                  CLIPBOARD DDECLIENT DDESERVER LINK TARGETCTRL


ΓòÉΓòÉΓòÉ 223. Library and sample programs ΓòÉΓòÉΓòÉ

Included with Visualizer Development are a number of utility and sample
programs that have been created using the product.

Sample programs with source code

Utility programs without source code

User Library functions


ΓòÉΓòÉΓòÉ 223.1. Sample programs with source code ΓòÉΓòÉΓòÉ

There are source code and window files for several sample applications. If you
chose to install the samples, then the Development Samples folder contains a
folder for samples in the installed language (called ENGLISH for the English
version). Inspect these objects for more information on how to write code for
menus, windows, and communication protocols.

For a description of each sample, see its help.


Syntax help
To examine the source code, use the Program editor. If you are not sure about
the use of one the keywords, highlight the word and select Syntax help on the
tool bar to display help for that keyword. (Some program keywords may not have
a dedicated help entry however, and a general help message may be displayed.)

Sample libraries of source code are provided in the FTB1DIR directory as
FTDENUL1.LIB and in the Development Samples folder as OBJECTS.LIB and
EXAMPLES.LIB.

Use the Library menu in the Program editor to read and copy blocks.


ΓòÉΓòÉΓòÉ 223.2. Utility programs without source code ΓòÉΓòÉΓòÉ

The utility programs listed below were also created using Visualizer
Development.  The source code for them is not supplied, but they are useful
demonstrations of the types of applications that can be created.  You may also
find some of them useful in their own right.  However they are not actually
part of the Visualizer Development product.

Note:   No guarantee is made for the suitability of the sample programs and
        applications and they are provided for educational use only.

The applications range between simple and complex and give you some indications
of how Visualizer Development can be used. Comprehensive online help is
available. There is reference information (including syntax diagrams) for
objects, attributes, functions, statements, and events.

To obtain this help, you can:

o Use Help Index on the Help menu

o Use Syntax help on the Help menu of the Program editor

o Use Contents or Search from within any Visualizer Development help

o In the Program editor, position the typing cursor over any word in your own
  code, and press the help key (F1).

There is extensive hyperlinking throughout this help.  You may find it helpful
to maximize the Help windows when you are using this facility for detailed
information.

Utility   Description

Classer   This simple application applies the Visualizer Development class to
          objects which have lost their class and cannot therefore be opened by
          the system.  (The class will be lost if you edit an object with an
          editor that does not support extended attributes.)

Debugger  Use the debugger application to walk through your compiled ASL
          applications. You can set break points in the ASL program that's
          executing and query or modify any variables and objects in the
          program.

          From the menu bar, you can use:

   Debug to perform all the debug step activities
   Selected to set break points on lines, or add a variable to be watched
   View to display the Data and Objects that are active in the current program
   Help to display Help...

Set DEBUGPATH in your config.sys to list the paths that will be searched for
source code. The source code search order is as follows:

Current location of the application to debug,

   o <Module name>.PRG
   o <Module name>.A80
   o <Module name>

          if this search is unsuccessful, then the paths in the DEBUGPATH
          environment variable will be searched,

   o <Module name>.PRG
   o <Module name>.A80
   o <Module name>

          Use the on-line help provided with the application for more
          information on how to debug applications.

X_refer   This utility interrogates a program file and provides a list of the
          variables contained within it and the program blocks which refer to
          these variables.  There is also an indication of how many program
          lines are comments and how many lines are executable.

AppView   Visualizer Development puts all compiled output into application
          files which cannot normally be read or changed without recompiling.
          With this utility you can list the contents of an application or
          objectstore and view any windows or string files they contain.

StringEdit This is the most complex example provided. With this application you
          can add string vectors to application files.  You can use these
          vectors, for example, as look-up tables.

          You can use ASL to create vectors for use as a look-up table at run
          time.  With this application you can create such lists within the
          application and store them statically rather create them dynamically.

          The application creates and uses string files with an extension .STR.
          Commenting is allowable in the source files, and the program
          reference for each active line can be indicated.  The created string
          vectors are then compiled into a new application while the source is
          stored for future reference.

          Since this application attempts to demonstrate a complete and
          extensive application, it supports the clipboard, has online help,
          and indicates how a file-handling application could be configured.

Win_Doc   This application displays windows and allows you to look at the
          attributes of controls on a window.  The attributes can also be
          printed from the application.


ΓòÉΓòÉΓòÉ 223.3. User Library functions ΓòÉΓòÉΓòÉ

This section contains a list of procedures which are available in the User
Library.  The User Library is shipped with Visualizer, so you do not have to
copy it to your destination systems. The User Library is supplied as the file
USERLIB.A95. You can access the procedures in it by opening this file as an
objectstore with a statement like:


OPEN OBJECTSTORE MyLib,
  NAME     = "USERLIB.A95",
  LOCATION = S.Control.Path     ! Default path for the User library

then declaring the library procedures that you need, with a statement like:


LIBRARY ASL "MyLib..AppDevl", FILE_PUT, THUMB
For example:


LIBRARY ASL "MyLib..AppDevl",
 Files,          ! File selection dialog. Returns filename
 Thumb,          ! Re-Calculate Scroll Thumb size
 Help_Setup,     ! Load help files...
 File_Put,       ! Fast Load a file from disk into ASL array
 File_Get,       ! Fast Write a file to disk from and ASL array
 App_Help,       ! Filter standard Help menus selections.
 Print,          ! Std function to print Graphics, Windows or Text
 Trace           ! Program tracing/de-bugging

then calling the procedures as required, with statements like:


CALL FILE_PUT(FileName, POINTER("VecName"))
! The contents of VecName[0] are written to the
!  file named in the FileName variable.

Procedures available for use in your applications are listed below:

APP_HELP
          Filters help selections from a SELECT block.


                    ON SELECT
                       IF APP_HELP() RETURN
                     = "t..win"
                    ON SELECT
                    DO
                      IF APP_HELP()
                        RETURN
                     ...

APP_ICON
          Puts an application icon on a user application.

AS_Send(File, Class, AppCode, ASName, Dialog)
          Used to exchange Report and Chart specifications with Host AS.

          Return codes from the function are:

   0  Sent OK (though conversion may have failed)
   1  Unknown error
   2  AS object failed to open
   3  Import canceled from password window
   4  Host AS error receiving file


                    RC = AS_Send(
                     "C:\DSS\MyRep",  ! Fully qualified name of
                                      ! file to be sent to Host AS
                     "REPORT"      ,  ! Class to be sent, REPORT or CHART
                     "DEV"         ,  ! The Host AS Application code
                                      !   to receive the file
                     "Repone"      ,  ! The Host AS file name
                     0             )  ! Dialogs or Messages to be shown?
                                      !   1=Yes, 0=No
                    IF RC > 0 ! Failed, take action to correct..
                    DO
                     ...

Dec2Hex(number)
          Returns the formatted Hex character string of number. The returned
          string is formatted as  "x0000 0000".

EXPORTDATA(pStream, pTable)
          Copies data from a table to a STREAM object in the format specified
          by the FORMAT attribute of the STREAM object.

          pStream is a pointer to a STREAM object, and pTable is a pointer to a
          TABLE object. If pStream does not point to an SFILE or SMEMORY, or
          pTable does not point to a TABLE, the call fails with error 7690. If
          the FORMAT attribute of the STREAM is not set to a supported format,
          or an error occurs during the export, the return code is nonzero.

          The supported formats are:

   "IXF"     Integrated exchange format
   "PCIXF"   PC version of IXF supported by DB2 for OS/2
   "DIF"     Data interchange format
   "EDIF"    Extended DIF
   "Flat"    ASCII file
   "List"    A comma-separated value (CSV file)
   "DBF"     dBASE III format
   "Text"    Tab-separated text

          For example, the following code opens a table named MYDATA in D:\DATA
          and exports it to a new file named MYDATA.DIF in the same directory.


                    OPEN TABLE TabHand,
                     NAME     = "MyData",
                     LOCATION = "D:\DATA"

                    OPEN SFILE stream,
                     NAME     = "MyData.DIF",
                     LOCATION = "D:\DATA",
                     MODE     = "WRITE",
                     FORMAT   = "DIF"

                    rc = EXPORTDATA(POINTER(stream[0]), POINTER(tabhand[0]))

          An SMEMORY object can be used to place a DIF file on the clipboard or
          pass it to another program that is expecting a STREAM, without
          putting the exported data on disk.

FILE_GET (Filename, pVector)
          Gets file from OS/2 and puts it in an ASL vector.


                    CALL FILE_GET(filename, POINTER("vecname"))
           filename  is the fully qualified file name, and vecname  is the name
          of the vector to be placed into or read from the file.

FILE_PUT (Filename, pVector)
          Puts ASL vector into an OS/2 file.


                    CALL FILE_PUT(filename, POINTER("vecname"))
           filename  is the fully qualified file name, and vecname  is the name
          of the vector to be placed into or read from the file.

FILES(filename, location, class, window)
          Allows selection from a list of OS/2 files. Returns the file name
          selected by the end user.


                    LET F_NAME = FILES ("myfile.fil", "D:\DSS","IBMTABLE","tables")
                       ! parameters are file name, location, class, and window name.

HELP_SETUP(helpfile,objectname)
          Invokes Information Presentation Facility (IPF) against a help file
          specified by the end user.


                    ON START
                    DO
                      OPEN HELP help_h
                      ! help_h is handle for HELP object
                      CALL HELP_SETUP("myhelp.hlp","help_h")
                      ! myhelp.hlp is your compiled help file

IMPORTDATA(pTable, pStream)
          Copies data from a STREAM object to a TABLE object in the format
          specified by the FORMAT attribute of the STREAM object.

           pTable  is a pointer to a TABLE object, and pStream  is a pointer to
          a STREAM object. If pTable  does not point to a TABLE, or pStream
          does not point to an SFILE or SMEMORY, the call fails with error
          7690. If the FORMAT attribute of the STREAM is not set to a supported
          format, or an error occurs during the import, the return code is
          nonzero.

          The supported formats are:

   "IXF"     Integrated exchange format
   "PCIXF"   PC version of IXF supported by DB2 for OS/2
   "DIF"     Data interchange format
   "Flat"    ASCII file
   "List"    A comma-separated value (CSV file)
   "DBF"     dBASE III format
   "Text"    Tab-separated text

          For example, the following code opens an empty table named MYDATA in
          D:\DATA and imports data from the existing file named MYDATA.DIF in
          the same directory.


                    OPEN TABLE tabhand,
                     NAME="MyData",
                     LOCATION="D:\DATA",
                     MODE="WRITE"
                    OPEN SFILE stream,
                     NAME="MyData.DIF",
                     LOCATION="D:\DATA",
                     MODE="READ",
                     FORMAT="DIF"
                    rc = IMPORTDATA(POINTER(tabhand[0]), POINTER(stream[0]))

PARSE_LOC(location)
          Resolves the current location.


                    LET Location = PARSE_LOC(Lcn)

PRINT (handle,Description)
          Prints Vectors, graphics and windows.


                    LET description="myprint"
                    OPEN WINDOW win,,
                        TITLE = "My window",
                        SIZEX = 200,
                        SIZEY = 50
                    OPEN GRAPHIC fred, win,
                        X = 50,
                        Y = 50,
                        SIZEX = 100,
                        SIZEY = 100
                        DEFINE text[0]
                        INSERT Text[0] = "Mary"
                        INSERT Text[0] = "had "
                        INSERT Text[0] = "a   "
                        INSERT Text[0] = "little"
                        INSERT Text[0] = "lamb."
                    rc = PRINT (POINTER("Text"),Description)
                      ! or
                    rc = PRINT (POINTER("Win"),Description)
                      ! or
                    rc = PRINT (POINTER("fred"),Description)

PRINTREQUEST(PrinterName, Name, Dialog)
          PRINTREQUEST will open a PRINTER object and set the objects
          DESCRIPTION attribute to the selected printer (the default system
          printer or one selected from a dialog).

          PrinterName , if specified, should match one of the Workplace Shell
          defined printers. If PrinterName  is specified as "*", the Workplace
          Shell default printer is assumed. If PrinterName  is not specified or
          there is no default printer, a list of printers is presented to the
          user (subject to the setting of  Dialog ).

          Dialog  controls the presentation of dialogs. The default is 1, but
          the parameter can be set to 0 to suppress the presentation of
          dialogs.  If the dialog is suppressed, the default printer specified
          in Print Manager is used.

          If specified, Name  should match the instance name of the calling
          application. It is used to construct the title of the printer
          selection dialog. It may be a character string of up to 255 bytes. If
          not specified, the default title of Printer selection will be used.

          After the PRINTREQUEST action has been issued (and any dialogs
          closed), an ON PRINT event is generated. The ON PRINT event is passed
          the handle to the open PRINTER object.

Proc_Var()
          The Proc_Var() function provides access to variables located in
          another (nested) procedure.  For example if a user uses a dialog
          object within one graphical procedure to assign a user variable, the
          contents of that variable can be made available to other called
          graphical procedures.

          To use the function, link to the user library and include Proc_Var as
          a required function (as shown in the OPEN OBJECTSTORE statement
          above). The single parameter for the function is the name of the
          required procedure variable:


                    Name =Proc_Var("@Name")

          Name  is a procedure variable that the used has entered via a typed
          response dialog.

SAVEAS(filename,location)
          Provides a save as dialog


                    CALL SAVEAS(Filename,FileLocation)

SCROLL(n,entries,clones,topline)
          Reacts to a scroll request.


                    LET topline= SCROLL(1,entries,clones,topline)

SEND (FileName)
          Used to send a file to another user with a mail system installed.


                    rc = SEND (FileName)

TRACE()
          The TRACE() function provides access to a trace log, the trace log is
          filled by the application when the TRACE ON statement is executed.
          The TRACE OFF statement stops the filling of the trace log.  Leaving
          a block or procedure executes an automatic TRACE OFF.  If you want
          the trace to continue in the next executed block, the next block must
          contain another TRACE ON.

          TRACE() will only work with programs compiled using the Program
          editor. TRACE() can be called at any time during program execution to
          display. the trace log.

          To use the function, link to the user library and include TRACE as a
          required function (as shown in the OPEN OBJECTSTORE statement above).
          Include the TRACE ON and TRACE OFF statements at the desired points
          for each block in your program.  The CALL to TRACE() need only occur
          once, for example in the ON START block.

          Compile and run your program.  When the application reaches the
          TRACE() function, it displays a window containing the trace log. The
          trace log updates dynamically and is additive. The CLEAR button in
          the trace window reinitializes the trace log.

          The trace remains available only while the Program editor which
          compiled the program is still active.  (It is not enough to re-open
          Program editor on the source code while you run a previously compiled
          version. Even if there are no changes to the source, you must compile
          the source from the Program editor for TRACE() to work.)  If you
          close the editor, the provided trace will be of line numbers only.

          Ensure that all TRACE statements and calls to the TRACE() function
          are removed before finalizing your code.

THUMB(entries,topline,clones)
          Positions thumb on a scroll bar.


                    LET T..mainwin'VSCRLBARPOSN=THUMB(entries, top_line, clones)
                       ! entries is the total number of entries in the list,
                       ! top_line is the starting line for the displayed list,
                       ! clones is the number of displayed clones

THUMBSIZE(entries, clones)
          Controls size of thumb on a scroll bar.


                    LET T..Mainwin'VTHUMBSIZE = THUMBSIZE(entries,clones)

VALID_NAME(filename,location)
          Checks whether a file name and location are valid.


                    LET Check = VALID_NAME(FileName, FileLoc)

ViewScreen(session)
          Use ViewScreen to surface a host Communications Manager screen from
          your ASL application.  The session  parameter is the communications
          manager Short Session ID.


                    rc = ViewScreen("A")! maximize the host A session
          The function returns the HLLAPI return code from the action (zero if
          successful).


ΓòÉΓòÉΓòÉ 224. Using the C programming language ΓòÉΓòÉΓòÉ

Programs written in the C language can be invoked as functions from within ASL
applications.

C programs invoked like this can:

o Receive parameters and return a value
o Access objectstores (subject to the same constraints as the invoking ASL
  program)
o Perform some of the special operations ASL programs can perform.

C code can only be used if it is packaged as a Dynamic Link Library (DLL). The
code can be 16-bit code compiled using the Large Model convention for calling
the entry points, (all pointers must be far) or it can be 32-bit code.

An ASL program can then incorporate a LIBRARY DLL statement to identify the C
code entry points. The LIBRARY statement in ASL is described more fully in .

C code entry points are called, by the CALL statement or as a function, in the
same way as any other ASL entry point- CALL entry or entry(). The DLL is loaded
on the first call to any of its entry points. It remains attached to the
calling task until that task terminates.

This diagram shows the relationships of the various components of ASL
applications that include parts written in C. It shows a C function invoked by
C():

 ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ       ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ      ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
 Γöé         Γöé   all   Γöé       Γöé  C()   Γöé       Γöé
 Γöé  ASL program  Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ>Γöé ASL     Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ>Γöé  C program  Γöé
 Γöé  for the main  Γöé statements Γöé interpreter Γöé      Γöé  in a DLL  Γöé
 Γöé  dialog     Γöé       Γöé       Γöé<ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ       Γöé
 Γöé         Γöé       Γöé       Γöé  return  Γöé       Γöé
 Γöé         Γöé       ΓööΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ      ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
 Γöé         Γöé         Γöé OdeDsGetHandleofVariable Γöé
 Γöé         Γöé         Γöé              Γöé
 Γöé         Γöé       ΓöîΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ      ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
 Γöé         Γöé       Γöé       Γöé      Γöé       Γöé
 Γöé         Γöé       Γöé ASL     Γöé<ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ>Γöé  C      Γöé
 Γöé         Γöé       Γöéobjectstore  Γöé      Γöéfunction   Γöé
 Γöé         Γöé       Γöé manager   Γöé      Γöé  library   Γöé
 Γöé         Γöé       Γöé       Γöé      Γöé       Γöé
 ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ       ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ      ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

The ASL interface to C

The C interface to ASL


ΓòÉΓòÉΓòÉ 224.1. The ASL interface to C ΓòÉΓòÉΓòÉ

Arguments passed internally to the function are described by a provided term,
ODEDSARGS. This is a composite structure showing:

o Where the returned value should be placed
o How many arguments were given in the C function call
o The value of each argument.

It is described more fully in .

The value returned by a function is a scalar of type ODEDSRC. It can be nonzero
to signal an error, invoking the ASL program's ON ERROR block.

Note:   The stack size available to a C program called from ASL is 16KB.


ΓòÉΓòÉΓòÉ 224.2. The C interface to ASL ΓòÉΓòÉΓòÉ

C functions called from ASL programs can make use of ASL data and facilities by
calling functions in a DLL which is provided. This DLL is ODECAPI.DLL. Its
entry points and associated data structures are defined in the header file
ODECAPI.H supplied with Visualizer Development.

 ODECAPI.H  supports compilation by 16-bit C compilers or by the 32-bit IBM C
SET/2 compiler.

Accessing objectstore variables

Data types in Value Control Blocks

Passing arguments to C functions

Return codes and error handling

Functions for accessing objectstores


ΓòÉΓòÉΓòÉ 224.2.1. Accessing objectstore variables ΓòÉΓòÉΓòÉ

Some of the functions require data values to be retrieved from or placed into
objectstore variables. As the data type of such values cannot be assumed, this
information must be included with the value itself. ODECAPI.H therefore
includes a definition of a structure, ODEDSVCB (Value Control Block), for this
purpose:


typedef struct _ODEDSVCB    /* vcb Value Control Block  */
                            /* used for passing data    */
                            /* across the interface     */
{
  ODEDSTYPE      dstType;   /* Data type                */
  UCHAR          uchSpare;
  USHORT         usMaxLen;  /* String area max. length  */
  PDSBUF         plstString; /* Pointer to string area  */
  ODEDSELEMENT   edsVar;    /* Element Number           */
  union
  {
    DSVCBD        vcbdDate; /* Date                     */
    double        dFloat;   /* Floating long real       */
    ODEDSHANDLE   dshVar;   /* Handle Decision-Support  */
                            /* Component pointer        */
    SHORT         sInteger; /* Signed integer           */
    USHORT        usCurLen; /* Current string length    */
    LONG          lInteger; /* Signed 32-bit integer    */
    DSVCBT        vcbtTime; /* Time                     */
    USHORT        usInteger; /* Unsigned 16-bit         */
  } data;
} ODEDSVCB;

When the type ODEDSVCB is used in the declaration of variables, the C compiler
must generate a packed structure (with no slack bytes for word alignment).

Examples of how to use a Value Control Block are given with some of the
functions described in .


ΓòÉΓòÉΓòÉ 224.2.2. Data types in Value Control Blocks ΓòÉΓòÉΓòÉ

The first element of the structure defines the type of data the structure
contains, and dictates the way the rest of the structure should be defined. The
values it can take and the way the rest of the structure is used are as
follows:

NULL (ODE_DS_TYPE_NULL)
          A null is being passed. The rest of the structure is ignored.

Date (ODE_DS_TYPE_D)
          The date type means the  data.vcbdDate  component should be valid.
          This is a structure itself:


                    typedef struct _DSVCBD   /* vcbd specifies a date */
                    {
                      USHORT    usYear;
                      UCHAR     uchMonth;
                      UCHAR     uchDay;
                      UCHAR     uchPeriod;
                    } DSVCBD;

          Each component is the numeric representation of that part of a date,
          For example, the fourteenth of March 1990 would be represented by
          usYear = 1990, uchMonth = 3, and  uchDay = 14.

Float (ODE_DS_TYPE_F)
          This is a double float value, in the component data.dFloat.

ODE_DS_TYPE_H
          A handle and element are being passed, to reference either an object
          or a variable. The ASL POINTER() function generates values of this
          type for a variable. An object identifier is also of this type.
          Unlike the other types of data this can only be used for transferring
          references to the C code. The components of the structure that are
          instantiated are edsVar  and data.dshVar  the element and handle. The
          element component is only of interest if the pointer is a reference
          to an object instance.

Signed Short Integer (ODE_DS_TYPE_I)
          The data is treated as a signed short integer. The valid component of
          the structure is data.sInteger.

Signed Long Integer (ODE_DS_TYPE_L)
          The data is treated as a signed long integer. The valid component of
          the structure is data.lInteger.

String (ODE_DS_TYPE_S)
          This is a string. The length of the string is held in the component
          data.usCurLen. The string pointer is plstString  and does not have to
          be null terminated.

Time (DE_DS_TYPE_T)
          The time type is a structure itself:


                    typedef struct _DSVCBT /* vcbt specifies a time */
                    {
                      UCHAR     uchHour;
                      UCHAR     uchMinute;
                      UCHAR     uchSecond;
                      UCHAR     uchCentisec;
                    } DSVCBT;

          As with the date structure each component is numeric.

Unsigned short Integer (ODE_DS_TYPE_U)
          The data in this case is in data.usInteger.

Null Terminated String (ODE_DS_TYPE_V)
          This type indicates the data is a null terminated string, thus the
          plstString component is the only other valid component and must
          contain a null terminated string.

DBCS String (ODE_DS_TYPE_G)
          Exactly similar to the type ODE_DS_TYPE_S except that the string in
          question should contain DBCS characters

Note:   The interface may change some data values. There may be truncation in
        either direction, or a number given as ODE_DS_TYPE_U might be given
        back as ODE_DS_TYPE_F (if ODE_DS_TYPE_U is not explicitly asked for).


ΓòÉΓòÉΓòÉ 224.2.3. Passing arguments to C functions ΓòÉΓòÉΓòÉ

ODEDSARGS defines the composite argument that is passed by ASL to a C function:


typedef struct
  {
    USHORT cArguments;          /* Number of arguments      */
    USHORT usSpare;             /* for alignment            */
    PODEDSVCB pvcbRetValue; /* Ptr to vcb for returned value */
    PODEDSVCB apvcbArguments[ODE_DS_MAX_ARGS];
           /* List of pointers to VCBs passed as parameters */
  } ODEDSARGS;

The values passed as parameters are not returned when the function ends. On
return, if the entry point was called as a function, the data in  pvcbRetValue
is its returned value. The cArguments  component contains the actual number of
parameters in the array. The array size (and thus the maximum number of
arguments) is defined in the header file, ODECAPI.H. The structure used for the
returning value and passing parameters is described in .

Numeric parameters may be passed in any of the numeric formats.
OdeDSConvertVCB  may be used to convert to a specific numeric format.


ΓòÉΓòÉΓòÉ 224.2.4. Return codes and error handling ΓòÉΓòÉΓòÉ

ODECAPI.H defines a data type ODEDSRC for return codes. This data type allows
any nonnegative integer value. All of the DSS functions return a ODEDSRC value.
Zero means successful execution. Anything else causes an ASL error to be raised
with the ODEDSRC  value available in the  A.System.ErrorInfo  vector.


ΓòÉΓòÉΓòÉ 224.2.5. Functions for accessing objectstores ΓòÉΓòÉΓòÉ

This section lists the C functions available for accessing ASL objectstores.

For each function, a description and an example are given. In the examples:

o The declaration:


    ODEDSRC retc;

  has previously been given.

o For 16-bit code, the Large model of C is assumed. Even so, the C far
  attribute is used in all the function definitions and pointer declarations in
  the header files to avoid dependence on any particular model.

o A  +  in the first position of a comment indicates a parameter that is for
  receiving a returned value.

o The OdeDsGetHandleOfVariable function is often shown for completeness and
  clarity. In practice,while handles may be passed as parameters,
  OdeDsGetHandleOfVariable is more likely to be used during initialization.

The following entry points are provided for the C code to utilize. A variety of
actions can be performed, which essentially mirror the functionality of
equivalent ASL statements. These entry points are defined along with any types
required in the header ODECAPI.H. All the functions return with zero if they
are successful. There are failure codes detailed in ODECAPI.H and one of these
is returned when an error is detected.

OdeDsGetHandleOfVariable
          This function obtains the reference to a variable in the Visualizer
          environment. It can, if required, create the variable.

OdeDsDeleteContentsOfVariable
          deletes the contents of a Visualizer variable.

OdeDsDefineSizeOfVariable
          defines or redefines the size of a Visualizer variable.

OdeDsDeleteValue
          deletes a specific value from a Visualizer variable.

OdeDsDeleteVariable
          deletes a Visualizer variable.

OdeDsQuerySizeOfVariable
          returns the number of instantiated elements in the variable.

OdeDsGetKey
          returns the row number in a table where the data values given match
          the column values in the table, OR creates a new row with them.

OdeDsQueryValue
          returns the value in the specified handle, element pair.

OdeDsQueryIndex
          generate and return an index on a table using the alternate key
          specified.

OdeDsInsertValue
          Inserts value given at the element specified in the variable denoted
          by the handle.

OdeDsDisplayMessage
          Displays a message on the string, the text of which is contained in
          the message file.

OdeDsQueryVariableNames
          Returns the list of names of the variables contained in the specified
          group.

OdeDsPutValue
          inserts or replaces a value at the handle element specified.

OdeDsPutTraceMessage
          Writes the message given into the trace file.

OdeDSGetAndSetBreak
          Gets and, if required, sets the control break status.

OdeDsCallAction
          This entry point allows access to the actions upon an object
          instance.

OdeDsQueryAttr
          This returns the value of a specified attribute of a specified
          object.

OdeDsModifyAttr
          This modifies the value of the specified object attribute to be the
          value specified.

          OdeDsConvertVCB
          This converts the contents of a VCB to a specific data format.

          OdeDsQueryCaseMapTable
          This function provides the case mapping table used to transform a
          character to its upper-case equivalent.

          OdeDsQueryCollatTable
          This function provides the collating sequence table used to transform
          a character to its position in the sorting or collating sequence.

OdeDsGetHandleOfVariable

OdeDsDefineSizeOfVariable

OdeDSDeleteContentsOfVariable

OdeDSDeleteValue

OdeDSDeleteVariable

OdeDSQuerySizeOfVariable

OdeDSDisplayMessage

OdeDSGetKey

OdeDSQueryValue

OdeDSInsertValue

OdeDSQueryIndex

OdeDSQueryVariableNames

OdeDSPutValue

OdeDSPutTraceMessage

OdeDSGetAndSetBreak

OdeDSCallAction

OdeDSQueryAttr

OdeDsModifyAttr

OdeDSConvertVCB

OdeDSQueryCaseMapTable

OdeDSQueryCollatTable


ΓòÉΓòÉΓòÉ 224.2.5.1. OdeDsGetHandleOfVariable ΓòÉΓòÉΓòÉ

This function provides a reference to a Visualizer variable, the variable can
be created or already exist. The reference will be required for use in other
entry points in the interface. The reference is known as a handle and is valid
only during the current session. The function definition is:


ODEDSRC ODEENTRY OdeDsGetHandleOfVariable (
       PODEDSHANDLE  phdsVar,
       PCHAR         pszVarName,
       USHORT        usoption,
       PBOOL         pfNewVar);

The first parameter phdsVar is a pointer to the returning handle, (the type
ODEDSHANDLE is defined in ODECAPI.H). The pszVarName is the name of the
variable (ASCIIZ string). The third parameter allows the user to define if the
variable is to be created or not, the values are defined as ODE_DS_CREATEIT and
ODE_DS_DONT. The option to create a variable creates the variable only if it
does not exist already. The final parameter is a flag. It is only valid when
the ODE_DS_CREATEIT option is used, and it is set to TRUE if and only if, the
variable is created. A newly created variable has an indeterminate type and
shape. It can be explicitly shaped (using OdeDsDefineSizeOfVariable). Otherwise
it becomes a scalar on its first use.

In this example the user expects the variable to be created if it does not
already exist.


ODEDSHANDLE countref;
BOOL        created;
ODEDSRC     returncode;
 returncode = OdeDsGetHandleOfVariable
               (&countref,         /* Note must compile  */
                "Count",           /* Large for address  */
                ODE_DS_CREATIT,
                &created);
 if (created)
 ...


ΓòÉΓòÉΓòÉ 224.2.5.2. OdeDsDefineSizeOfVariable ΓòÉΓòÉΓòÉ

This function allows the dimension of a variable to be defined or redefined,
thus a single dimension array can be extended for example. The function does
not work for all variables. If the reference is to a column of a table or a
scalar with a valid integer value then one cannot change its dimension, it
allows the redefinition only of single dimension arrays. The definition of the
function is:


ODEDSRC ODEENTRY OdeDsDefineSizeOfVariable (
       ODEDSHANDLE  hdsVar,
       ODEDSELEMENT edsVar,
       PODEDSVCB    pvcbInitVal);

The nearest ASL equivalent is the DEFINE statement, the equivalent of


DEFINE newvar[10]

would be:


ODEDSVCB    myvcb;          /* Vcb for initial value    */
  ODEDSHANDLE thatone;      /* Handle for the array     */
  ODEDSRC     retc;
  BOOL        created
  myvcb.type = DSS_TYPE_U;         /* Set integer type  */
  myvcb.data.u = 0;                /* Set value to zero */
  retc = OdeDsGetHandleOfVariable  /* Get Handle        */
            (&thatone,
             "NewArray",
             ODE_DS_CREATIT,
             &created
             );
  if (!retc && created)
    {
     retc =  OdeDsDefineSizeOfVariable
                ( thatone,     /* define var to have 10 */
                  10,          /* elements              */
                  &myvcb );
 ...


ΓòÉΓòÉΓòÉ 224.2.5.3. OdeDSDeleteContentsOfVariable ΓòÉΓòÉΓòÉ

This function is used to remove all elements from a Visualizer variable. The
function does not delete the variable itself.  The function just takes the
handle of the variable.


ODEDSRC ODEENTRY OdeDSDeleteContentsOfVariable (
       ODEDSHANDLE hdsVar);
                          /* handle of variable/vector */

If used successfully against an array then the array will have zero elements.
The function is equivalent to the ASL CLEAR statement.


ΓòÉΓòÉΓòÉ 224.2.5.4. OdeDSDeleteValue ΓòÉΓòÉΓòÉ

This function is used to delete an element, identified by its element number,
from a Visualizer variable.


ODEDSRC ODEENTRY OdeDSDeleteValue (
       ODEDSHANDLE  hdsVar,
       ODEDSELEMENT edsVar);

Example:


ODEDSHANDLE somevar;          /* Handle of a variable  */
  ODEDSRC     retc;
 ...
                           /* Have to obtain ref to    */
                           /* var, most likely by use  */
                           /* of                       */
                           /* OdeDsGetHandleOfVariable */
  retc = OdeDSDeleteValue ( somevar, 5);
                 /* removes the 5 value from the array */

Note upon successful return the array contains one fewer elements. The above
example is equivalent to the ASL DELETE statement.


ΓòÉΓòÉΓòÉ 224.2.5.5. OdeDSDeleteVariable ΓòÉΓòÉΓòÉ

This function is used to delete a Visualizer variable.


ODEDSRC ODEENTRY OdeDSDeleteVariable (
       ODEDSHANDLE hdsVar);

Example:


ODEDSHANDLE somevar;       /* Handle of a variable     */
  ODEDSRC     retc;
 ...
                           /* Have to obtain ref to    */
                           /* var, most likely by use  */
                           /* of                       */
                           /* OdeDsGetHandleOfVariable */
  retc = OdeDSDeleteVariable( somevar );

This call destroys the variable being referenced. This leaves the handle
referencing the variable, but it is marked not valid and is not be usable
unless it is created again.

The above example is equivalent to the ASL DELETE statement.


ΓòÉΓòÉΓòÉ 224.2.5.6. OdeDSQuerySizeOfVariable ΓòÉΓòÉΓòÉ

This function returns the number of elements in an array (or one for a scalar).
If the variable is not valid then the number of entries is not valid.

The function for this is:


ODEDSRC ODEENTRY OdeDSQuerySizeOfVariable (
       ODEDSHANDLE   hdsVar,
                          /* Handle of variable/vector */
       PODEDSELEMENT pedsElems);
             /* return number of elements in var/vector*/

For example if the number of entries in an array is unknown then:


ODEDSHANDLE  somevar;      /* Handle of a variable     */
  ODEDSRC      retc;
  ODEDSELEMENT noofentries;
 ...
                           /* Have to obtain ref to    */
                           /* var, most likely by use  */
                           /* of                       */
                           /* OdeDsGetHandleOfVariable */
  retc = OdeDSQuerySizeOfVariable
            ( somevar,
              &noofentries);

This function is equivalent to the ASL statement ENTRIES.


ΓòÉΓòÉΓòÉ 224.2.5.7. OdeDSDisplayMessage ΓòÉΓòÉΓòÉ

This function displays a message on the screen.


ODEDSRC ODEENTRY OdeDSDisplayMessage (
       USHORT usMessageNo,
                      /* Number of message */
       USHORT usHelpPanelId,
             /* Id of Help Panel, 0 if None            */
       PCHAR  pszMessage,
             /* String to be inserted in message       */
             /* (if any)                               */
       PCHAR  puchButton);
             /* value of button pressed                */
             /* '1' = OK,    '2' = CANCEL, '3' = ABORT,*/
             /* '4' = RETRY, '5' = IGNORE, '6' == YES,  */
             /* '7' = NO,    '8' = ENTER               */

The first parameter is the number of a message. The second is the number of the
help panel to be associated with the message (zero if none). The third is a
string to be used as an insert (if there is one in the message) otherwise NULL.
The final parameter is the address of a character to allow the button that was
pushed by the user to be returned. The characters correspond to the value of
button pressed:

'1' OK
'2' CANCEL
'3' ABORT
'4' RETRY
'5' IGNORE
'6' YES
'7' NO
'8' ENTER

Example:


ODEDSRC retc;
  CHAR    button;


  retc = OdeDSDisplayMessage
            (0,
             0,
            "Starting execution now...",
            &button);

This function is equivalent to the ASL DIALOG statement.


ΓòÉΓòÉΓòÉ 224.2.5.8. OdeDSGetKey ΓòÉΓòÉΓòÉ

This function looks up a given key value in a given table and, if the given key
is found, provides the corresponding element number. Otherwise depending on the
option may generate the row with those values.


ODEDSRC ODEENTRY OdeDSGetKey (
       ODEDSHANDLE   hdsVar,
             /* handle of a column in table            */
       USHORT        usOption,
             /* Option CREATEIT or DONT (if row does   */
             /* not exist already                      */
       PODEDSELEMENT pedsElemNum,
             /* Row number located or created          */
       PODEDSRETINFO pdsretFind,
             /* code if found or not or created        */
       USHORT        cNoKeys,
             /* Count of key values in array           */
       PODEDSVCB     avcbSearchKeys);
             /* array of values to use as search       */
             /* condition on key columns of the table  */

hdsVar    is the handle of an arbitrarily chosen column in the table (which
          column is chosen has no bearing on the result of the function).

usOption  which can take on of the following values:

   ODEDSCREATEIT meaning "create a new key, and therefore a new row, if one of
             this value does not already exist in the table".
   ODEDSDONT meaning "don't create a new key".

pedsElemNum is the place in which the row number corresponding to the given key
          is returned. If the key doesn't exist, and ODEDSDONT was given as the
          option, the element number of the next higher key in the table is
          returned (number of entries plus 1, if there is no higher key).

pdsretFind is the place where clarifying information about the key is returned.
          It can take any of the following values:

   ODE_DS_ROW_EXISTS meaning "the key was found in the table".
   ODE_DS_ROW_NOTFOUND meaning "the key was not found, and has not been
             created".
   ODE_DS_ROW_CREATED meaning "the key didn't exist, but has been created".

Example:


ODEDSHANDLE  somecol;       /* Place for column handle */
  ODEDSELEMENT elno;        /* Place for element num.  */
  ODEDSRETINFO keyinfo;     /* Place for key info.     */
  ODEDSVCB     val;         /* Place for value.        */
  ODEDSRC      retc;
  val.type = ODE_DS_TYPE_V; /* Set string type.        */
  val.sptr = "Bilbo";       /* Set value to "Bilbo".   */
  val.maxlen = 5;           /* and set size of data.   */
  retc = OdeDsGetHandleOfVariable
             (&somecol,     /* Get handle of a column  */
              "t1.salary" );  /* in the table.         */
  retc = OdeDSGetKey
              (somecol,     /* Req'd column.           */
               ODE_DS_DONT, /* Don't create a new row. */
               &elno,       /* Returned element number.*/
               &keyinfo,    /* Returned key info.      */
               1,           /* One key value follows.  */
               &val );       /* Vcb for "Bilbo".       */

If the key Bilbo did not exist then the entry where it would exist is returned
as the row number. If the function fails then the returns are not valid.

The above example is equivalent to the ASL statement:


LET elno = ROW(t1.salary{"Bilbo"},">=")

except that elno  is an ASL variable this time.


ΓòÉΓòÉΓòÉ 224.2.5.9. OdeDSQueryValue ΓòÉΓòÉΓòÉ

This function is used to obtain a Visualizer data value.


ODEDSRC ODEENTRY OdeDSQueryValue (
       ODEDSHANDLE  hdsVar,
             /* handle of variable                     */
       ODEDSELEMENT edsVar,
             /* element number of value in variable    */
       PODEDSVCB    pvcbValue,
             /* value returned                         */
       ODEDSTYPE    dstConv);
             /* Type val to be converted to for return */

If the conversion type is set to unknown, then the data is returned as the type
that matches its content. Visualizer types and the corresponding C type for
this are:

NUMERIC                 may be any numeric type
CHARACTER               ODE_DS_TYPE_S
DATE                    ODE_DS_TYPE_D
TIME                    ODE_DS_TYPE_T
POINTER                 ODE_DS_TYPE_H
GRAPHIC                 ODE_DS_TYPE_G
NULL                    ODE_DS_TYPE_UNKNOWN.

The data can be forced to a particular type, but note that if the type is
incompatible the function fails.


ODEDSHANDLE a_ptr;       /* Handle                     */
  ODEDSVCB    myvcb;     /* Place to receive answer.   */
  char s_area[DSS_MAXLEN];
                         /* In case answer is a string,*/

 ...
  myvcb.sptr = s_area;       /* connect area to vcb.   */
  myvcb.maxlen = ODE_DS_MAXLEN; /* Give length of area.*/
  retc = OdeDSQueryValue
             ( a_ptr, 3,  /* Get value of 3rd element, */
               &myvcb,    /* into this vcb, and        */
               DSS_TYPE_UNKNOWN);
                          /* mind how I get it.        */

This returns the value of the third element of the array referenced by a_ptr.
If the element is set to zero then the first element of the array is accessed.
The value is in myvcb.

If the required variable is a scalar, use 1 for the element number.


ΓòÉΓòÉΓòÉ 224.2.5.10. OdeDSInsertValue ΓòÉΓòÉΓòÉ

This function is used to insert a new element in a Visualizer array, and assign
a value to that element.


ODEDSRC ODEENTRY OdeDSInsertValue (
       ODEDSHANDLE  hdsVar,
             /* Handle referencing Variable            */
       ODEDSELEMENT edsVar,
             /* Element to be inserted into, 0 appends */
       PODEDSVCB    pvcbValue);
             /* Value to be inserted                   */

Example:


ODEDSHANDLE a_ptr;         /* Place to receive handle. */
  ODEDSVCB    myvcb;       /* Place to receive answer. */
  ODEDSRC     retc;
  myvcb.sptr = "Bilbo";    /* Connect string to vcb.   */
  myvcb.maxlen = 5;        /* (Probably unnecessary.)  */
  retc = OdeDsGetHandleOfVariable
             ( &a_ptr,     /* Get handle for variable. */
               "MyArray" );
  retc = OdeDSInsertValue
             ( a_ptr, 3,   /* Insert 3rd        */
               &myvcb );   /* element ("Bilbo") */

If the function is successful, then a new element is created as element 3 in
the Visualizer array MyArray, containing  "Bilbo". A failure leaves the
variable unaffected.

The above example is equivalent to the ASL statement:


INSERT MyArray[3] = "Bilbo"


ΓòÉΓòÉΓòÉ 224.2.5.11. OdeDSQueryIndex ΓòÉΓòÉΓòÉ

This function generates a Visualizer array that will contain the row numbers of
a table which are the index based on the keys given.


ODEDSRC ODEENTRY OdeDSQueryIndex (
       ODEDSHANDLE  hdsVar,
             /* Handle of variable to receive the      */
             /* element numbers of the index           */
       USHORT       cbNoKeys,
             /* Count of the keys in the index         */
       PCHAR        achAscOrDesc,
             /* array of key directions, - descending  */
             /* + ascending. 1 to 1 correlation with   */
             /* vector of key handles                  */
       PODEDSHANDLE ahdsKeyRefs);
             /* vector of key handles                  */


ΓòÉΓòÉΓòÉ 224.2.5.12. OdeDSQueryVariableNames ΓòÉΓòÉΓòÉ

This function is used to obtain a list of Visualizer data object names, names
of groups and tables within a data area, or names of variables or columns in a
group or a table. The result is placed in a Visualizer variable, which can
subsequently be accessed using other functions in the interface.


ODEDSRC ODEENTRY OdeDSQueryVariableNames (
     ODEDSHANDLE   hdsVar,
             /* Handle of vector for return of names   */
     PCHAR         pszItemName,
             /* string denoting the item which         */
             /* contains the items whose names are     */
             /* returned                               */
     PODEDSELEMENT pedsElems);
             /* Number of entries in the result        */

Example:


ODEDSHANDLE names;            /* Handle for WF array.  */
  ODEDSELEMENT size;          /* For size of array.    */
  retc = OdeDsGetHandleOfVariable
             (&names,         /* handle for variable   */
              "T..Names");
  retc = OdeDSQueryVariableNames
             (names, "User",  /* Get names of groups   */
              &size);         /* in User data area     */

If successful, the Visualizer variable T..Names contains a list of the names of
all the groups and tables in the data area called .User. The C variable called
names contains the handle of the Visualizer variable T..Names. If the function
fails, T..Names is unchanged.

The above example is equivalent to the ASL statement:


NAMES Names = "User"


ΓòÉΓòÉΓòÉ 224.2.5.13. OdeDSPutValue ΓòÉΓòÉΓòÉ

This function is used to place a value in a Visualizer data element.


ODEDSRC ODEENTRY OdeDSPutValue (
       ODEDSHANDLE  hdsVar,
             /* Handle of variable/vector              */
       ODEDSELEMENT edsVar,
             /* Element number within vector           */
       PODEDSVCB    pvcbValue);
             /* Value to be placed at that position    */

Example:


ODEDSHANDLE ptr_array;       /* Handle for array of    */
                             /* pointers, established  */
                             /* by ASL program.        */
  ODEDSVCB ptr;              /* Place for handle.      */
  ODEDSVCB val;              /* Place for value.       */
  ODEDSRC  retc;
 ...
  val.type = DSS_TYPE_U;     /* Set integer type.      */
  val.data.usInteger = 19;   /* Set value to nineteen. */
 ...
  retc = OdeDsGetHandleOfVariable
            (&ptr_array,     /* Get handle of agreed   */
             "AgreedName");  /*    array of pointers   */
 ...
  retc = OdeDsQueryValue
            (ptr_array,10,   /* Required handle is 10th*/
             &ptr,           /* +element in ptr array. */
             DSS_TYPE_H);
 ...
  retc = OdeDsPutValue
            (ptr.data.h, 1,  /* Put established value  */
             &val);          /* (19) into    variable  */

If successful then the contents of the first or only element of the Visualizer
variable whose identifying handle is in the tenth element of the Visualizer
array called AgreedName will have been changed in accordance with the value
given by the ODEDSVCB val.

The above example is equivalent to the ASL statement:


LET (AgreedName)[10] = 19

This example shows an alternative to OdeDsGetHandleOfVariable, for obtaining
handles of Visualizer variables. It is assumed that some ASL program has
previously established a Visualizer array of pointers (using the POINTER
function), called Pointer.


ΓòÉΓòÉΓòÉ 224.2.5.14. OdeDSPutTraceMessage ΓòÉΓòÉΓòÉ

OdeDSPutTraceMessage can be used to put a time stamped message in the system
trace, S.System.Trace.


ODEDSRC ODEENTRY OdeDSPutTraceMessage (
       PCHAR pszMessage);
                 /* String to be placed in trace       */

Example:


retc = OdeDSPutTraceMessage ("Starting execution now...");

If successful then message has been added to the system trace file,
S.System.Trace.


ΓòÉΓòÉΓòÉ 224.2.5.15. OdeDSGetAndSetBreak ΓòÉΓòÉΓòÉ

This function can be used to check, and set or clear if desired, the status of
control breaks. Once a control break is set the ON BREAK block executes upon
return to ASL, (if, and only if, breaking is enabled). set fClear to TRUE to
cause Ctrl+breaks to be cleared.


ODEDSRC ODEENTRY OdeDSGetAndSetBreak (
       PODEDSRETINFO pdsretReturn,
                 /* Ctrl+Break status                  */
       USHORT        fClear);
                 /* Clear Ctrl+Break status            */


ΓòÉΓòÉΓòÉ 224.2.5.16. OdeDSCallAction ΓòÉΓòÉΓòÉ

This function performs actions against certain Visualizer objects. The handle
and element pair of parameters must be passed to the code from ASL. Thus the
objects that can be accessed must be open before the C code is executed (with
the exception of data). The only other object than data that access is allowed
to is the TABLE object.

The call also takes an ASCIIZ string that is the action to be performed. The
actions are detailed with the objects. The parameters are identical as for an
action, thus if an action takes three parameters these must be provided, along
with the count being set to three.


ODEDSRC ODEENTRY OdeDSCallAction (
       ODEDSHANDLE  hdsVar,  /* 'Handle' of Object >   */
       ODEDSELEMENT cedsVar, /* 'Element' of Object>   */
                             /*  (received  as type    */
                             /* ODE_DS_TYPE_H)         */
       PCHAR        pszAction,
             /* String denoting the ACTION             */
       USHORT       cbArgs,
             /* Count of arguments in VCBs             */
       PODEDSVCB    avcbArgs,
             /* array of input arguments               */
       PODEDSVCB    pvcbResult);
             /* value returned by the action           */

To use this function on an object other than data one has to pass a pointer to
the object id from ASL as a parameter. This provides (in the VCB) both the
handle and the element that form the object instance information.


ΓòÉΓòÉΓòÉ 224.2.5.17. OdeDSQueryAttr ΓòÉΓòÉΓòÉ

This is similar to the previous function, it operates on the same objects and
requires the object to be identified in the same way.

A single value is returned as object attributes have to be scalar.


ODEDSRC ODEENTRY OdeDSQueryAttr (
       ODEDSHANDLE  hdsVar,
                /* 'Handle' of Object >                */
       ODEDSELEMENT cedsVar,
                /* 'Element' of Object>(received       */
                /* as type ODE_DS_TYPE_H)              */
       PCHAR        pszAttr,
                /* string denoting Attribute           */
       PODEDSVCB    pvcbVal,
                /* The value of the attribute          */
       ODEDSTYPE    dstConv);
                /* Type to converted the value to      */

To use this function on an object other than data, pass a pointer to the object
id from ASL as a parameter. This provides (in the VCB) both the handle and the
element that form the object instance information.


ΓòÉΓòÉΓòÉ 224.2.5.18. OdeDsModifyAttr ΓòÉΓòÉΓòÉ

Again similar to the previous function only this time the value is applied to
the attribute, not got from it.


ODEDSRC ODEENTRY OdeDsModifyAttr (
       ODEDSHANDLE  hdsVar,
             /* 'Handle' of Object >                   */
       ODEDSELEMENT cedsVar,
             /* 'Element' of Object>(received          */
             /*   as type ODE_DS_TYPE_H)               */
       PCHAR        pszAttr,
             /* string denoting Attribute              */
       PODEDSVCB    pvcbVal);
             /* Value attribute to be set to           */

To use this function on an object other than data, pass a pointer to the object
id from ASL as a parameter. This provides (in the VCB) both the handle and the
element that form the object instance information.


ΓòÉΓòÉΓòÉ 224.2.5.19. OdeDSConvertVCB ΓòÉΓòÉΓòÉ

This converts the contents of a VCB to a specific data format.


ODEDSRC ODEENTRY OdeDSConvertVCB (
  PODEDSVCB      pvcbValue,
  ODEDSTYPE      dstConv);

The first parameter pvcbValue is a pointer to the VCB to be converted, and the
second parameter dstConv is the type is is to be converted to. If dstConv
specifies a string type, the VCB pointer variable plstString must point to the
area where the result will be placed.

This example converts the first argument to a USHORT.


retc =
   OdeDsConvertVCB( args->apvcbArguments[0],ODE_DS_TYPE_U );


ΓòÉΓòÉΓòÉ 224.2.5.20. OdeDSQueryCaseMapTable ΓòÉΓòÉΓòÉ

This function provides the case mapping table used to transform a character to
its uppercase equivalent.


ODEDSRC ODEENTRY OdeDSQueryCaseMapTable(
  PCHAR          casemap);
The parameter casemap is a pointer to a 256-byte area which will receive the
case mapping table. The contents of this table depend on the national language
currently in use.


ΓòÉΓòÉΓòÉ 224.2.5.21. OdeDSQueryCollatTable ΓòÉΓòÉΓòÉ

This function provides the collating sequence table used to transform a
character to its position in the sorting or collating sequence.


ODEDSRC ODEENTRY OdeDSQueryCollatTable(
  PCHAR          collate);
The parameter collate is a pointer to a 256-byte area which will receive the
collating sequence table. The contents of this table depend on the national
language currently in use.


ΓòÉΓòÉΓòÉ 225. DDE C functions ΓòÉΓòÉΓòÉ

This section lists the C functions which provide the services allowing ASL
developers to create server and client applications which exchange data and
commands using the Dynamic Data Exchange (DDE) mechanism. These functions also
allow developers writing in C to create similar applications directly because
the services are callable from C programs.

See the online reference manuals for OS/2 2.0 and the OS/2 Programming Guide
Vol II, PM Window Programming Interface for more information on the DDE
protocol.

Sample DDE client and server programs are supplied with Visualizer Development.

Introduction to DDE Services

Functions


ΓòÉΓòÉΓòÉ 225.1. Introduction to DDE Services ΓòÉΓòÉΓòÉ

Overview


ΓòÉΓòÉΓòÉ 225.1.1. Overview ΓòÉΓòÉΓòÉ

The DDE services are made up of several function calls, the majority of which
relate closely to the underlying DDE functions. There are also functions to
manage the DDE environment (see below).

The functions remove the inherent asynchronous processing where possible by
only returning to the caller when the desired function has been performed.
Exceptions are when DDE events, such as unsolicited termination requests or
requests for changed data, are received. The caller can supply a function that
will be called by DDE services to handle DDE events.

Function calls are serialized within conversations.

The caller of the DDE services supplies a pointer which will be updated to
identify the response received and point to the DDE data structure when the
data is available. It is the caller's responsibility to check the return codes
and the responses to see if the operation was successful.

DDE Environment

DDE Event

New data types

List of DDE Service functions

Tracing

Error Information


ΓòÉΓòÉΓòÉ 225.1.1.1. DDE Environment ΓòÉΓòÉΓòÉ

A DDE environment can be either a client or a server environment.

It is established by a call to the DDE service function OdeDDOpen. It is a PM
window environment and consists of an object window, a message queue which
receives DDE messages, and its associated window procedure which runs on a
separate OS/2 thread (called the DDE PM thread) to that of the DDE service
caller.

The DDE PM thread causes additional threads to be created, one per
conversation, to process the messages it receives.

Multiple DDE environments can be created by an application.


ΓòÉΓòÉΓòÉ 225.1.1.2. DDE Event ΓòÉΓòÉΓòÉ

A DDE event is said to occur when a valid DDE message is received by an object
window which is part of a DDE environment and the message is not a response to
a previous message. Such a message is said to be an event message.


ΓòÉΓòÉΓòÉ 225.1.1.3. New data types ΓòÉΓòÉΓòÉ

The following new data types are introduced:

Type           Usage

DDERESP        A structure containing the response to a DDE request.

PDDERESP       A pointer to a DDERESP structure.

HDDEENV        A structure containing the handle of a DDE environment.

PHDDEENV       A pointer to a HDDEENV structure.

HDDECONV       A structure containing the handle of a DDE conversation.

PHDDECONV      A pointer to a HDDECONV structure.

The above data types are defined in FTBDDE.H and are used in DDE Service
function calls.


ΓòÉΓòÉΓòÉ 225.1.1.4. List of DDE Service functions ΓòÉΓòÉΓòÉ

The function calls provided are:

Function                      Description

OdeDDOpen                     Establish a DDE environment.

OdeDDShut                     Destroy a DDE environment.

OdeDDInitiate                 Initiate a DDE conversation.

OdeDDTerminate                Terminate a DDE conversation.

OdeDDRequest                  Request a data item from a DDE server.

OdeDDAdvise                   Request updates whenever a data item changes.

OdeDDUnadvise                 Request that updates for a data item be
                              discontinued.

OdeDDExecute                  Send a command string to a server for execution.

OdeDDPoke                     Send a data item to a server.

OdeDDData                     Send a data item to a client.

OdeDDAck                      Acknowledge a DDE function.

OdeDDRegisterConversation     Register a conversation not initiated by DDE
                              services.

OdeDDGetMsg                   Get the next event message for a specified DDE
                              conversation.

OdeDDQueryServers             Query the applications and topics supported by
                              all active servers.

C function prototypes for the above functions can be found in FTBDDE.H.

LINKER Import file definitions for the above functions can be found in
FTBDDE.LIB.

The functions are packaged in a DLL called FTBDDE.DLL.

The functions use SYSTEM linkage.


ΓòÉΓòÉΓòÉ 225.1.1.5. Tracing ΓòÉΓòÉΓòÉ

To assist problem determination with DDE, trace information can optionally be
written which shows DDE Service function calls, PM DDE function calls, PM DDE
messages and associated parameters.

The information will be written to file FTBDDE in the directory identified by
the FTB1DIR environment variable.

Tracing is equivalent to the DDE tracing done in ASL.


ΓòÉΓòÉΓòÉ 225.1.1.6. Error Information ΓòÉΓòÉΓòÉ

To assist problem determination with DDE, error messages are written to a file.
Warning messages are also written to the file if DDE Tracing has been
requested.

The messages will be written to file FTBLOG in the directory identified by the
FTB1DIR environment variable.

Error information is also provided by the function return code and, optionally,
in a reason code variable provided by the caller.

Return Codes

Return Codes


ΓòÉΓòÉΓòÉ 225.2. Functions ΓòÉΓòÉΓòÉ

The functions are described below. More information can be found in the include
file FTBDDE.H.

OdeDDOpen

OdeDDShut

OdeDDInitiate

OdeDDTerminate

OdeDDRequest

OdeDDAdvise

OdeDDUnadvise

OdeDDExecute

OdeDDPoke

OdeDDData

OdeDDAck

OdeDDRegisterConversation

OdeDDGetMsg

OdeDDQueryServers

User-supplied Initiate function

User-supplied Event function

Function Return Codes


ΓòÉΓòÉΓòÉ 225.2.1. OdeDDOpen ΓòÉΓòÉΓòÉ

Establish a DDE environment.


ret = OdeDDOpen(UINT type,
      UINT (* _System  initfun) (
      HDDECONV, PDDEINIT, PVOID,
      PCHAR *, PCHAR *, PCONVCONTEXT *),
      void (* _System eventfun) (
      HDDECONV, PVOID),
      PVOID eventparm,
      PUINT pctrl_break,
      PCHAR pbreak_enabled,
      HDDEENV * phddeenv,
      UINT trace,
      PUINT pcode)

type           Identifies the type of environment to be created.

initfun        See . Entry point of a function which will be called to process
               WM_DDE_INITIATE messages for this DDE environment. Must be NULL
               if this environment is a DDE Client.

eventfun       See Entry point of a function which will be called to process
               event messages for this DDE environment or NULL if this
               environment does not support event messages.

eventparm      Pointer to a parameter which will be passed to eventfun when it
               is called to process event messages for this DDE environment or
               NULL if no parameter is to be passed.

pctrl_break    A pointer to a flag which, if set, will cause a wait for a
               response from a DDE conversation partner to be suspended and
               control returned to the caller of a DDE function as if a timeout
               had occurred.

pbreak_enabled  A pointer to a flag which determines whether or not the
               pctrl_break flag is to be ignored the first five times it is
               pressed. If FALSE the pctrl_break flag is ignored until it has
               been pressed at least six times. If TRUE the pctrl_break flag is
               honoured when it is pressed.

phddeenv       A pointer to the handle of the created DDE environment.

trace          Perform the debug action appropriate to the value.

pcode          A pointer to an integer to receive additional information, if
               available, about an error.

Must be called before attempting to use DDE functions. initfun must be
specified if a DD_TYP_SERVER environment is being opened. See  for more
information. If eventparm is NULL all event messages will be discarded. This is
only valid for a client environment which does not wish to issue ADVISE calls.

The pctrl_break and pbreak_enabled parameters enable the user of DDE services
to terminate a DDE request which has not completed in an acceptable time
period. They are the only way to terminate a DDE request when an infinite
timeout has been specified. The use of pctrl_break and pbreak_enabled should be
considered when the value for the timeout parameter in other DDE service
function is being chosen.


ΓòÉΓòÉΓòÉ 225.2.2. OdeDDShut ΓòÉΓòÉΓòÉ

Destroy a DDE environment.


 OdeDDShut(HDDEENV hddeenv,
           UINT timeout,
           UINT trace,
           PUINT pcode)

hddeenv     The handle of the DDE environment which is to be destroyed.

timeout     If no response is received within timeout milliseconds, control is
            returned to the caller. If timeout is zero, the service does not
            wait for a response. If timeout is -1, the service waits until a
            response is available.

trace       Perform the debug action appropriate to the value.

pcode       A pointer to an integer to receive additional information, if
            available, about an error.

Must be called when DDE functions are no longer required in this DDE
environment. All active conversations will be terminated. The DDE environment
to be destroyed should previously have been created by this application.

If a Timeout occurs the ability of the OdeDDShut caller to use DDE services
will not be affected. However,  it will not be possible to use this environment
again and applications which are in conversation with the OdeDDShut caller may
not have removed their references to it and they may require application
specific action to ensure they can function correctly.


ΓòÉΓòÉΓòÉ 225.2.3. OdeDDInitiate ΓòÉΓòÉΓòÉ

Initiate a DDE conversation.


 OdeDDInitiate(HDDEENV hddeenv,
               CHAR * application,
               CHAR * topic,
               PCONVCONTEXT pcctxt,
               PDDERESP pdderesp,
               HDDECONV * phddeconv,
               UINT timeout,
               UINT trace,
               PUINT pcode)

hddeenv     Handle of DDE environment.

application  Name of application. Must not be NULL.

topic       Name of topic. Must not be NULL.

pcctxt      A pointer to a conversation context structure or NULL.

pdderesp    A pointer to the DDE response area which contains a pointer to the
            DDEINIT structure which was returned by the server with which
            conversation was established.

phddeconv   A pointer to the handle of the conversation which was established,
            or NULL if no conversation was established.

timeout     If no response is received within timeout milliseconds, control is
            returned to the caller. If timeout is zero, the service does not
            wait for a response. If timeout is -1, the service waits until a
            response is available.

trace       Perform the debug action appropriate to the value.

pcode       A pointer to an integer to receive additional information, if
            available, about an error.

The DDE environment for hddeenv  must have previously been created via a
OdeDDOpen call.

This call is valid for a client only. If a server responds which is already in
conversation with this DDE environment, a return code will be set to indicate
this and no new conversation will be established. If a Timeout occurs the
conversation will be terminated.


ΓòÉΓòÉΓòÉ 225.2.4. OdeDDTerminate ΓòÉΓòÉΓòÉ

Terminate a DDE conversation.


 OdeDDTerminate(HDDECONV hddeconv,
                UINT timeout,
                UINT trace,
                PUINT pcode)

hddeconv    Handle of DDE conversation

timeout     If no response is received within timeout milliseconds, control is
            returned to the caller. If timeout is zero, the service does not
            wait for a response. If timeout is -1, the service waits until a
            response is available.

trace       Perform the debug action appropriate to the value.

pcode       A pointer to an integer to receive additional information, if
            available, about an error.

If a Timeout occurs no further conversations with this conversation partner
will be permitted from this DDE environment. It will be necessary to issue
OdeDDShut and OdeDDOpen in order to re-establish such a conversation.


ΓòÉΓòÉΓòÉ 225.2.5. OdeDDRequest ΓòÉΓòÉΓòÉ

Request a data item from a server application.


 OdeDDRequest(HDDECONV hddeconv,
              PDDESTRUCT pddestruct,
              ULONG ddeoptions,
              PDDERESP pdderesp,
              UINT timeout,
              UINT trace,
              PUINT pcode)

hddeconv    Handle of DDE conversation

pddestruct  A pointer to a DDESTRUCT  structure defining the data item
            required.

ddeoptions  Option list for WinDdePostMsg function.

pdderesp    A pointer to the DDE response area which contains a pointer to the
            DDESTRUCT structure which was returned by the server.

timeout     If no response is received within timeout milliseconds, control is
            returned to the caller. If timeout is zero, the service does not
            wait for a response. If timeout is -1, the service waits until a
            response is available.

trace       Perform the debug action appropriate to the value.

pcode       A pointer to an integer to receive additional information, if
            available, about an error.

The conversation must have previously been established using DDE services.


ΓòÉΓòÉΓòÉ 225.2.6. OdeDDAdvise ΓòÉΓòÉΓòÉ

Request that a data item be sent whenever it changes.


 OdeDDAdvise(HDDECONV hddeconv,
             PDDESTRUCT pddestruct,
             ULONG ddeoptions,
             PDDERESP pdderesp,
             UINT timeout,
             UINT trace,
             PUINT pcode)

hddeconv    Handle of DDE conversation

pddestruct  A pointer to a DDESTRUCT  structure defining the data item
            required.

ddeoptions  Option list for WinDdePostMsg function.

pdderesp    A pointer to the DDE response area which contains a pointer to the
            DDESTRUCT structure which was returned by the server.

timeout     If no response is received within timeout milliseconds, control is
            returned to the caller. If timeout is zero, the service does not
            wait for a response. If timeout is -1, the service waits until a
            response is available.

trace       Perform the debug action appropriate to the value.

pcode       A pointer to an integer to receive additional information, if
            available, about an error.

If the client DDE environment has been opened with a NULL event function it
will not be possible to process responses to ADVISE. In this case an error will
be returned when OdeDDAdvise is called.

The conversation must have previously been established using DDE services.

If FACKREQ was set in the status field of pddestruct , it is the caller"s
responsibility to issue the OdeDDAck function when it is ready to accept new
data. This may be done in eventfun.


ΓòÉΓòÉΓòÉ 225.2.7. OdeDDUnadvise ΓòÉΓòÉΓòÉ

Request that a previously established advise link be discontinued.


 OdeDDUnadvise(HDDECONV hddeconv,
               PDDESTRUCT pddestruct,
               ULONG ddeoptions,
               PDDERESP pdderesp,
               UINT timeout,
               UINT trace,
               PUINT pcode)

hddeconv    Handle of DDE conversation

pddestruct  A pointer to a DDESTRUCT  structure defining the data item to be
            unadvised.

ddeoptions  Option list for WinDdePostMsg function.

pdderesp    A pointer to the DDE response area which contains a pointer to the
            DDESTRUCT structure which was returned by the server.

timeout     If no response is received within timeout milliseconds, control is
            returned to the caller. If timeout is zero, the service does not
            wait for a response. If timeout is -1, the service waits until a
            response is available.

trace       Perform the debug action appropriate to the value.

pcode       A pointer to an integer to receive additional information, if
            available, about an error.

The conversation must have previously been established using DDE services.


ΓòÉΓòÉΓòÉ 225.2.8. OdeDDExecute ΓòÉΓòÉΓòÉ

Send a command string to a server for execution.


 OdeDDExecute(HDDECONV hddeconv,
              PDDESTRUCT pddestruct,
              ULONG ddeoptions,
              PDDERESP pdderesp,
              UINT timeout,
              UINT trace,
              PUINT pcode)

hddeconv    Handle of DDE conversation

pddestruct  A pointer to a DDESTRUCT  structure defining the commands to be
            executed.

ddeoptions  Option list for WinDdePostMsg function.

pdderesp    A pointer to the DDE response area which contains a pointer to the
            DDESTRUCT structure which was returned by the server.

timeout     If no response is received within timeout milliseconds, control is
            returned to the caller. If timeout is zero, the service does not
            wait for a response. If timeout is -1, the service waits until a
            response is available.

trace       Perform the debug action appropriate to the value.

pcode       A pointer to an integer to receive additional information, if
            available, about an error.

The conversation must have previously been established using DDE services.

Note that the caller will wait until the command string has executed.


ΓòÉΓòÉΓòÉ 225.2.9. OdeDDPoke ΓòÉΓòÉΓòÉ

Send an unsolicited data item to a server application.


 OdeDDPoke(HDDECONV hddeconv,
           PDDESTRUCT pddestruct,
           ULONG ddeoptions,
           PDDERESP pdderesp,
           UINT timeout,
           UINT trace,
           PUINT pcode)

hddeconv    Handle of DDE conversation

pddestruct  A pointer to a DDESTRUCT  structure defining the data item to be
            sent.

ddeoptions  Option list for WinDdePostMsg function.

pdderesp    A pointer to the DDE response area which contains a pointer to the
            DDESTRUCT structure which was returned by the server.

timeout     If no response is received within timeout milliseconds, control is
            returned to the caller. If timeout is zero, the service does not
            wait for a response. If timeout is -1, the service waits until a
            response is available.

trace       Perform the debug action appropriate to the value.

pcode       A pointer to an integer to receive additional information, if
            available, about an error.

The conversation must have previously been established using DDE services.


ΓòÉΓòÉΓòÉ 225.2.10. OdeDDData ΓòÉΓòÉΓòÉ

Send a data item from a server to a client application.


 OdeDDData(HDDECONV hddeconv,
           PDDESTRUCT pddestruct,
           ULONG ddeoptions,
           UINT trace,
           PUINT pcode)

hddeconv    Handle of DDE conversation

pddestruct  A pointer to a DDESTRUCT structure defining the data item to be
            sent.

ddeoptions  Option list for WinDdePostMsg function.

trace       Perform the debug action appropriate to the value.

pcode       A pointer to an integer to receive additional information, if
            available, about an error.

The conversation must have previously been established using DDE services.

If the data is being sent as a result of an ADVISE and FACKREQ is set on the
ADVISE, FACKREQ must be set on the OdeDDData response. In this case an ACK
event will occur at the server when the client has sent an ACK to indicate that
he is ready for more data.


ΓòÉΓòÉΓòÉ 225.2.11. OdeDDAck ΓòÉΓòÉΓòÉ

Acknowledge a DDE function.


 OdeDDAck(HDDECONV hddeconv,
          PDDESTRUCT pddestruct,
          ULONG ddeoptions,
          UINT trace,
          PUINT pcode)

hddeconv    Handle of DDE conversation

pddestruct  A pointer to a DDESTRUCT structure defining the type of
            acknowledgment.

ddeoptions  Option list for WinDdePostMsg function.

trace       Perform the debug action appropriate to the value.

pcode       A pointer to an integer to receive additional information, if
            available, about an error.

The conversation must have previously been established using DDE services.


ΓòÉΓòÉΓòÉ 225.2.12. OdeDDRegisterConversation ΓòÉΓòÉΓòÉ

Register that a DDE conversation has been established between two DDE
environments.


 OdeDDRegisterConversation(HDDEENV hddeenv,
                           HWND hwnd,
                           HDDECONV * phddeconv,
                           UINT timeout,
                           UINT trace,
                           PUINT pcode)

hddeenv     The handle of the caller"s DDE environment.

hwnd        The handle of the window with which the caller"s DDE environment is
            in conversation.

phddeconv   A pointer to the handle of DDE conversation created by this
            function.

timeout     If no response is received within timeout milliseconds, control is
            returned to the caller. If timeout is zero, the service does not
            wait for a response. If timeout is -1, the service waits until a
            response is available.

trace       Perform the debug action appropriate to the value.

pcode       A pointer to an integer to receive additional information, if
            available, about an error.

This function is intended to be used in situations where the conversation
handles have been determined by some other mechanism (Drag/Drop for example).

The DDE conversation handle returned by this function should be used in
subsequent DDE service function calls.


ΓòÉΓòÉΓòÉ 225.2.13. OdeDDGetMsg ΓòÉΓòÉΓòÉ

Get the next event message for a specified DDE conversation.


 OdeDDGetMsg(HDDECONV hddeconv,
             PDDERESP pdderesp,
             UINT timeout,
             UINT trace,
             PUINT pcode)

hddeenv     Handle of DDE conversation

pdderesp    A pointer to the DDE response area which contains a pointer to the
            DDE data structure which was sent with the message.

timeout     If no response is received within timeout milliseconds, control is
            returned to the caller. If timeout is zero, the service does not
            wait for a response. If timeout is -1, the service waits until a
            response is available.

trace       Perform the debug action appropriate to the value.

pcode       A pointer to an integer to receive additional information, if
            available, about an error.


ΓòÉΓòÉΓòÉ 225.2.14. OdeDDQueryServers ΓòÉΓòÉΓòÉ

Return a structure which contains information on which servers are active and
which topics they support.


 OdeDDQueryServers(HDDEENV hddeenv,
                   CHAR * application,
                   CHAR * topic,
                   PCONVCONTEXT pcctxt,
                   PPDDEINIT ppddeinit,
                   UINT     maxservers,
                   PUINT    pactualservers,
                   UINT timeout,
                   UINT trace,
                   PUINT pcode)

hddeenv       Handle of a DDE client environment previously established by the
              caller.

application   The name of the application for which information is requested,
              or NULL.

topic         The name of the topic for which information is requested, or
              NULL.

pcctxt        A pointer to a conversation context structure or NULL.

ppddeinit     A pointer to an area to receive the information. The information
              will returned as an array of pointers to DDEINIT structures.

maxservers    The maximum number of servers for which information is to be
              returned.

pactualservers  A pointer to a number which will contain the actual number of
              servers whose information has been returned.

timeout       If no response is received within timeout milliseconds, control
              is returned to the caller. If timeout is zero, the service does
              not wait for a response. If timeout is -1, the service waits
              until a response is available.

trace         Perform the debug action appropriate to the value.

pcode         A pointer to an integer to receive additional information, if
              available, about an error.

The DDE environment for hddeenv  must have previously been created via a
OdeDDOpen call.

This call is valid for a client only.

The DDEINIT structures returned by this function must be freed by the caller.


ΓòÉΓòÉΓòÉ 225.2.15. User-supplied Initiate function ΓòÉΓòÉΓòÉ

Validate WM_DDE_INITIATE messages received by a DDE environment.

The Initiate function indicates by its return code whether or not the request
to initiate a conversation is to be accepted.

Being caller-specific it is not possible to describe the processing for this
routine in detail here.

hddeconv      Handle of the DDE conversation which will be established if this
              function accepts the conversation.

pddeinit      A pointer to the DDEINIT structure which was sent with the
              WM_DDE_INITIATE message.

peventparm    A pointer to the event parameter which was specified on the
              OdeDDOpen for this DDE environment.

papplication  A pointer to the name of the application to be used in the
              WinDdeRespond function call.

ptopic        A pointer to the name of the topic to be used in the
              WinDdeRespond function call.

pconvcontext  A pointer to a conversation context structure to be used in the
              WinDdeRespond function call.


ΓòÉΓòÉΓòÉ 225.2.15.1. Return Codes ΓòÉΓòÉΓòÉ

This function should return a type UINT with one of the following values:

TRUE        Accept this conversation.

FALSE       Ignore this conversation.
The Initiate function operates to the following specification:

o It will be called from the PM window procedure for this DDE environment using
  SYSTEM linkage and should be reentrant.

o Addressing considerations - 32 bit mode

o The Initiate function should complete processing in a timely manner because
  it is called synchronously from a window procedure.

o A DDE server environment must support one application and topic. Thus it is
  not permissible for an Initiate function to return different values for
  application and topic for different invocations in the same DDE environment.

o If the Initiate function returns TRUE the papplication and ptopic pointers
  must point to non-NULL strings. The pconvcontext pointer may either be NULL
  or a pointer to a valid CONVCONTEXT structure.

o The memory for the application, topic, and conversation context must not be
  freed before the DDE environment has been shut.


ΓòÉΓòÉΓòÉ 225.2.16. User-supplied Event function ΓòÉΓòÉΓòÉ

Respond to event messages received by a DDE environment.

There will one instance of the event function for each conversation within a
DDE environment. An example of an event message would be a DDE message being
received which requested a data item.

The event function may call DDE services to respond to an event. For instance,
it may call OdeDDData in response to a OdeDDRequest event.

Being caller-specific it is not possible to describe the processing for this
routine in detail here.

hddeconv    Handle of the DDE conversation for which this event function is
            processing events.

peventparm  A pointer to the event parameter which was specified on the
            OdeDDOpen for this DDE environment or NULL if no event parameter
            was specified.


ΓòÉΓòÉΓòÉ 225.2.16.1. Return Codes ΓòÉΓòÉΓòÉ

This function should not return a value.

The event function should operate to the following specification:

o It will be called using SYSTEM linkage and should be reentrant. Each instance
  of the event function will run on a separate thread.

o Addressing considerations - 32 bit mode

o Mandatory operations:

   All events                      The function should obey the rules of PM DDE
                                   as they relate to operations within a
                                   conversation.

                                   The function should issue OdeDDGetMsg in a
                                   loop until the return code indicates that
                                   the function is to terminate.

   ADVISE/UNADVISE messages        It is the callers responsibility to provide
                                   a mechanism to stop adviseing on a certain
                                   item when an UNADVISE is received for that
                                   item.

   Termination                     OdeDDGetMsg will return an appropriate value
                                   when an unsolicited terminate message is
                                   received.

                                   The function must not issue DDE services
                                   which reference this conversation once it
                                   has been asked to terminate.


ΓòÉΓòÉΓòÉ 225.2.17. Function Return Codes ΓòÉΓòÉΓòÉ

DDE Services functions provide a return code to indicate their success or
otherwise. The return codes are structured into ranges relating to user errors,
environmental errors or internal errors.

The different ranges of return codes are shown below. C constants are defined
to delimit the ranges.

User errors

Environmental errors

Internal errors


ΓòÉΓòÉΓòÉ 225.2.17.1. User errors ΓòÉΓòÉΓòÉ

DD_RET_USER_FIRST               First message

DD_RET_USER_LAST                Last message

DD_RET_TYPE_INVALID             An invalid value for type was specified. User
                                action, correct the value and retry the
                                function call.

DD_RET_SERIALISEFLAGS_INVALID   An invalid value for serialiseflags was
                                specified. User action, correct the value and
                                retry the function call.

DD_RET_PHDDEENV_NULL            A NULL PHDDEENV pointer was specified. User
                                action, supply a valid pointer to a HDDEENV and
                                retry the function call.

DD_RET_PHDDECONV_NULL           A NULL PHDDECONV pointer was specified. User
                                action, supply a valid pointer to a HDDECONV
                                and retry the function call.

DD_RET_APPLICATION_NULL         A NULL application was specified. User action,
                                supply a non-NULL string and retry the function
                                call.

DD_RET_TOPIC_NULL               A NULL topic was specified. User action, supply
                                a non-NULL string and retry the function call.

DD_RET_PDDESTRUCT_NULL          A NULL PDDESTRUCT pointer was specified. User
                                action, supply a valid pointer to a DDESTRUCT
                                and retry the function call.

DD_RET_PDDERESP_NULL            A NULL PDDERESP pointer was specified. User
                                action, supply a valid pointer to a DDERESP and
                                retry the function call.

DD_RET_EF_NULL                  A NULL event function was specified. User
                                action, supply an event function and retry the
                                function call.

DD_RET_INITFUN_INVALID          An initiate function was not supplied for a
                                DD_TYP_SERVER. User action, supply an initiate
                                function and retry the function call.


ΓòÉΓòÉΓòÉ 225.2.17.2. Environmental errors ΓòÉΓòÉΓòÉ

DD_RET_ENV_FIRST                First message

DD_RET_ENV_LAST                 Last message

DD_RET_WAIT_TIMEOUT             No reply has been received within the specified
                                timeout period. User action, check the DDE
                                environment for missing or malfunctioning
                                components. Correct any problems found and
                                retry the operation.

DD_RET_SIP                      The DDE environment specified on this function
                                call has previously been shut. User action,
                                investigate the reason why it has been shut.
                                Correct any problems found and retry the
                                operation.

DD_RET_TIP                      The DDE conversation specified on this function
                                call has previously been terminated by this DDE
                                environment. User action, investigate the
                                reason why it has been terminated. Correct any
                                problems found and retry the operation.

DD_RET_UTIP                     The DDE conversation specified on this function
                                call has previously been terminated by the
                                conversation partner. User action, investigate
                                the reason why it has been terminated. Correct
                                any problems found and retry the operation.

DD_RET_INITIATE_FAILED          No response has been received to a
                                WinDdeInitiate function call. User action,
                                check the DDE environment for missing or
                                malfunctioning components. Correct any problems
                                found and retry the operation.


ΓòÉΓòÉΓòÉ 225.2.17.3. Internal errors ΓòÉΓòÉΓòÉ

DD_RET_INT_FIRST                First message

DD_RET_INT_LAST                 Last message

User action. No user action is required. Contact IBM for further assistance.

Chapter file for ftd94mst


ΓòÉΓòÉΓòÉ 225.3. Dummy heading ΓòÉΓòÉΓòÉ

Dummy para


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

expression is any expression that produces a numeric value.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

cosine is the cosine of the required angle.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

string1 is the destination string.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

string2 is the string to be inserted.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

number is the number of a word in string1 after which string2 is inserted.

If number is zero, ADDWORD() inserts string2 at the start of string1.

If number is omitted, ADDWORD() places string2 at the end of string1.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

separator is the character to be used as a word separator within the strings.
It can only be a single character string. If it is omitted, the separator
defaults to a space.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

expression is any numeric expression.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

type specifies the type of adjustment required, and takes one of the following
values: (the values can be abbreviated to a single letter)

"NEAREST"     Rounds to the nearest number. 5 is rounded up.

"UP"          Adjusts to the next higher number in a positive direction.

"DOWN"        Adjusts to the next lower number in a negative direction.

"TRUNCATE"    Truncates the number (removes the low order digits).

"BANKERS"     Rounds trailing 5s up if preceded by an odd number. Otherwise
              rounds them down.

If type is omitted, NEAREST is assumed.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

position specifies the number of decimal places required. A negative value for
position means an equivalent adjustment to the integer, not decimal, part of
the adjusted number. -1 rounds to tens,  -2 rounds to hundreds, and so on.

If position is not specified, or is zero, the value is adjusted to provide an
integer result.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

result is the array used to hold the result of the analysis.

If only one input array is specified (col1), then result is a one-dimensional
array.

If a column array is specified (col2), then result is a two-dimensional array.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

col1 is the first array to be scanned.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

col1vals is the array containing the values to be scanned for in col1. All
other values are ignored.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

col2 if specified, is the second array to be scanned.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

col2vals is the array containing the values to be scanned for in col2. All
other values are ignored.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

col3sum is an array with its values accumulated in the elements of result. If
omitted, a count of occurrences appears in result.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

sine is the sine of the required angle.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

tangent is the tangent of the required angle.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

ENABLE The BREAK ENABLE statement lets control breaks be recognized. A program
that enables breaks should contain an ON BREAK block. A program that does not
contain an ON BREAK block will be interrupted, but the break will remain
outstanding for the calling task to handle.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

DISABLE The BREAK DISABLE statement causes breaks to be deferred. Multiple
control breaks are recognized. After a sequence of six control breaks, a break
event is signaled even under a BREAK DISABLE condition. On entry to any ON
block, breaks are disabled.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

CHECK The BREAK CHECK statement lets a control break happen without changing
the BREAK ENABLE or BREAK DISABLE state.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

CANCEL The BREAK CANCEL statement cancels any outstanding control breaks.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

SIMULATE The BREAK SIMULATE statement simulates control break entered by an end
user at that point in the program. This is to allow programs to be tested.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

procedure is the name of a procedure, which must be defined elsewhere using a
PROCEDURE or LIBRARY statement, or an indirect reference to such a procedure.
object'action


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

object'action is the name of an object action routine.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

parameter can be any expression. The value of this expression is passed to the
routine. A maximum of twenty parameters can be passed in one CALL statement.
For a direct CALL to a procedure, the number of parameters on the CALL must
match the number of variables in the PROCEDURE statement. This restriction does
not apply to indirect procedure calls using procedure pointers. In this case,
parameter lists are truncated or extended with NULL values as necessary. For a
CALL to an action routine, the number of parameters can vary and is as defined
for the object involved. For a direct call to a procedure with no parameters,
the enclosing parentheses () can be omitted.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

string is the string to be searched.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

number is the position of the word in the string.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

separator is the character to be used to separate the words in the string.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

dinput is a decimal integer. Up to 20 integers may be used to create the
string.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

string is the string to be searched.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

number is the position of the word in the string.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

separator is the character to be used to separate the words in the string.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

variableref is the reference to the variable to be cleared.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

expression can be a variable or a one-dimensional array.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

start is the first element of the array given by expression that CLENGTH() is
to test. The default is 1.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

end is the last element that CLENGTH() is to test. The default is the last
element in expression.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

sep if provided, prevents the function from including trailing separators in
the count of characters.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

expression1 An expression of any data type.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

expression2 An expression of any data type.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

option Controls the behaviour of NULLs:

-1      Treat a NULL as lower than any non-NULL value. This is the default.
1       Treat a NULL as higher than any non-NULL value.
0       Treat a NULL as a NULL.

The result of COMPARE() can be:

-1        expression1 < expression2
1         expression1 > expression2
0         expression1 = expression2
NULL      option is 0, and either expression1 or expression2 is NULL


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

oldname is the original variable.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

newname is the variable to be copied to.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

StartElement is the start element in the source variable. (The default is
element one.)


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

Number is the number of elements to copy. (The default is all elements. If
Number is greater than the number of elements, all elements are copied.)


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

angle is the angle for which the cosine is required.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

expression is the data to be counted. It can consist of up to nine constants,
scalars, or vectors, separated by commas. A complete vector can be checked by
referring to its dictionary entry using the subscript [0].


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

target is the string onto which a new substring is to be overlaid.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

repstr is the new substring.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

num is number of the character (counting from the start of target, at which
overlaying is to start. If num is omitted, overlaying starts at the first
character in target.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

len is the number of characters in the target to be overlaid. The default is
the length of repstr.

If len is zero, repstr is inserted immediately before byte number num rather
than overlaying any part of target. If len is greater than the length of
repstr, repstr is not padded out to the right. Instead, the overlay still takes
place but excess characters up to len are removed. (This allows a short
substring to overlay a long substring.)


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

pad is the SBCS character used for padding target if the length of target is
less than number. Any pad parameter must be a single character. The default pad
character is a space.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

string is the string to be padded.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

length is the total number of characters (not bytes) to which string is to be
extended with pad characters. length must be at least as much as the original
length of string, but no more than the maximum system string length.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

type specifies how the padding is applied:

"L"   Leading-padding to the left of string
"T"   Trailing-padding to the right of string
"C"   Center-padding to both left and right of string.

The default is "L".


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

pad is the character with which the string is padded. pad must be a
one-character string. The default pad character is a space.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

strip specifies whether leading or trailing blanks should be removed before
padding:

"B"   Both-leading and trailing spaces removed
"N"   Neither-no leading or trailing spaces removed
"L"   Leading-only leading spaces removed
"T"   Trailing-only trailing spaces removed.

The default is "B".


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

expression1 gives a character string to be scanned.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

expression2 gives a string of one or more characters which are to be tested for
within expression1.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

start is the character position within expression1 from which the scan is to
start. The default for start is 1, the first character position.

If start is beyond the position of the last character of expression1, start is
assigned the position of the character at the end of the string..


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

end is the character position within expression1 at which the scan is to end.
The default for end is the final character position.

If the start position is greater than the end position, then scanning is done
from the last character of the string expression1 backwards to end.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

compare specifies the type of scan to be carried out. It can be one of the
comparison operators:

"="     Search for the first occurrence of expression2 in expression1. Case of
        characters is ignored for SBCS.  With DBCS, the characters are compared
        on a case-sensitive basis.

"\="    Search for the first nonoccurrence of expression2 in expression1. Case
        of characters is ignored for SBCS.  With DBCS, the characters are
        compared on a case-sensitive basis.

"=="    Search for the first occurrence of expression2 in expression1.
        Characters are compared on a case-sensitive basis.

"\=="   Search for the first nonoccurrence of expression2 in expression1.
        Characters are compared on a case-sensitive basis.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

type specifies the type of comparison to be performed:

"*"     Search expression1 for the entire string in expression2

"1"     Search expression1 for any character in expression2.

The default for type is  "*".


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

expression gives a value to be split.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

startpoint is the character position within expression from which the split is
to start (that is, the part to be extracted starts at this character position).
startpoint must be an integer.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

length gives the number of characters to be split off, or extracted. length is
optional. If length is omitted, the default value is from startpoint to the end
of the string.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

filler specifies the filler character. The filler character is any character
which, when present, is used to pad out the extracted part to the value of
length if there are not enough input characters.  This would happen if the
number of characters between startpoint and the end of expression is less than
the specified length. When a justify parameter is present, filler defaults to a
blank (" "). filler only pads up to the maximum string length.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

justify specifies how the extracted characters are placed in the output string,
assuming padding occurs. (If filler is not specified, a comma must be included
if justify is to be specified.)

The values permitted for justify are:

"L" Left justify (default)
"R" Right justify.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

string is the string to be trimmed.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

type specifies whether leading or trailing blanks should be removed:

"B" Both-leading and trailing spaces removed
"N" Neither-no leading or trailing spaces removed
"L" Leading-only leading spaces removed
"T" Trailing-only trailing spaces removed.

The default is "B".


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

string is the string to be tested.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

number is the number of the character required.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

separator is the separator to be used. The default separator is a space.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

variable is the string, or number to be converted.

The parameter is optional, if omitted it defaults to the current date.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

format is the format which describes the date.  If it is omitted, the default
short date format is used.

If the input is unambiguous, it will be converted correctly whether it follows
the specified format or not.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

options This is a list of any of the following keywords in any order.

LOCAL     Data is local to a block. This is the default if the declaration is
          within a block.

TASK      Data is local to the task. This is the default if the declaration is
          outside all blocks.

GLOBAL    Data is global.

NULL      Data may take NULL values.

NONNULL   Data may not take NULL values. This is the default.

CLEAR     The data is cleared when it is allocated.

DEFINED   Storage is not allocated for the data until a DEFINE statement is
          executed. This is only valid for TASK data.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

datatype This is one of ASL datatypes:

o NUMERIC
o CHARACTER
o DATE
o TIME
o POINTER
o GRAPHIC
or it can be

o UNTYPED

indicating that the variable has no fixed data type.

For GLOBAL data only, the datatype may also be any Object Class.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

limit This can be specified for CHARACTER, GRAPHIC and UNTYPED data, and limits
the number of characters that can be held by the variable. If it is omitted, it
defaults to [1].


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

name This is the name of the variable. It is a single-part name which follows
normal name rules. This indicates that the data is an array, and specifies the
extent and dimensions. Arrays can be one dimensional or two dimensional. If it
is omitted, the variable is a scalar.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

initializer This is used to initialize a scalar, or all elements of an array.
DECLARE statements must be placed at the top of the event or procedure, before
any other ASL statements.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

variableref is the name of the array or table being defined.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

exp1 is an expression which, in the absence of expression exp2, gives a number
which is the number of elements in a one-dimensional array.

If exp1 is specified along with exp2, exp1 is the number of elements in the
first dimension of a two-dimensional array. Both exp1 and exp2 can be integers
or expressions which produce integers.

If exp1 is given as an asterisk, then the variable is a one-dimensional array
with no entries, typically a column of a table. The asterisk indicates that
there can be any number of elements.

The columns of a table are usually defined with an asterisk to indicate that
there can be any number of rows. After applying DEFINE to each column, you must
call the SETKEYS() action on the TABLE object in order to identify the key
columns.

When exp1 is an asterisk, exp2 and exp3 do not apply.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

exp3 is any expression, the value of which can be assigned to all new elements
in the variable.

If exp3 is not specified, then all elements of the variable are initialized to
NULL.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

expression is the expression to be tested. If the data type is not NULL, the
value 1 (true) is returned. Otherwise, the value 0 (false) is returned.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

radians is the value to be converted from radians to degrees.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

variableref is the variable which is the subject of the deletion.  This can be
a scalar variable or an array. A complete row of a table of which variableref
is a column can be deleted. If it is an array, all or selected elements of it
can be deleted.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

expression1 gives up to 16 values in the key columns of a table, and these are
used to identify the row in the table you wish to delete.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

expression2 specifies an element in a one-dimensional array.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

string is the string from which words are to be deleted.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

start is the number of the first word to be deleted. is the total number of
words to be deleted. If number is omitted, all the words in the string after
start are deleted. If number exceeds the number of remaining words, all
remaining words are removed and no error results.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

separator is the character to be used as a word separator within the strings,
and can only be a single-character string. It is optional and defaults to a
space if omitted.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

messageid is the identifier of the message template to be used.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

text is the text to be inserted into the message template.

The message templates are as follows:

"FTB0001", "FTB10001" Progress message
"FTB0002", "FTB10002" Information message
"FTB0003", "FTB10003" Warning message
"FTB0004", "FTB10004" Error message with OK push button only
"FTB0005", "FTB10005" Error message with OK and Cancel push buttons
"FTB0006", "FTB10006" Error message with Retry and Cancel push buttons
"FTB0007", "FTB10007" Error message with Abort, Retry, and Ignore push buttons
"FTB0008", "FTB10008" Error message with Yes and No push buttons.

All message templates create a temporary window for displaying a message. The
templates with four-digit numbers display a message prefix, including the text
"FTB". The templates with five-digit numbers do not display the message prefix.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

expression1 is the dividend.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

expression2 is the divisor.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

expression3 is the numeric expression that will be returned when expression2
evaluates to zero or NULL. If this parameter is omitted, NULL is returned when
expression2 evaluates to zero or NULL, and no error message is shown.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

variable is a single-value variable. When a set of statements is executed
repeatedly, variable is set at the start of each iteration.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

start gives the starting value for a range of values specified by start:limit.
limit gives the final value for a range of values specified by start:limit.

Repetition ends when the increment variable is greater than limit for
incrementing loops, or less than limit for decrementing loops.  If this is true
of the start value, the loop terminates immediately and statements is not
executed.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

step is an optional step value which can accompany the range of values
specified by start:limit. If this parameter is omitted, it defaults to 1.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

statements is one or more ASL statements to be grouped together by this
DO...END. This may be empty.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

expr1 must be an expression which yields a value of data type DATE or TIME.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

expr2 may yield a value of the same type as expr1 or a number.  If it is a DATE
or TIME value, then expr1 is subtracted from this value to provide the result.
This result is expressed in the units specified by type, and is numeric. expr2
- expr1 can be a positive or negative value.

If expr2 is not a DATE or TIME value, then it must be a number, positive or
negative, of whatever units are specified by type. expr1 is adjusted
accordingly, and the result is a DATE or TIME.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

type gives the units of expr2. If expr1 is a DATE, type can be:

"P"  Periods
"D"  Days (default)
"W"  Weeks
"M"  Months
"Y"  Years.

If the data type of expr1 is DATE, then the default type is "D" (Days).

If expr1 is a TIME, type can be:

"H"  Hours
"M"  Minutes
"S"  Seconds (default)
"C"  Hundredths of a second
"T"  Thousandths of a second.

If the data type of expr1 is TIME, then the default type is "T".


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

period gives the number of periods in a day, and can be used only if expr1 is a
date and type is "P". period can be any number between 2 and 48 (a day with
just one period is merely a day).  The first possible period number in any date
is always 0- so periods may range from 0 to 47. Note that, if you use multiple
dates in a calculation, both must be based on the same number of periods per
day.

Unless period is specifically set, a date assignment always sets it to 0.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

statementlist is the set of statements to be executed if the associated IF
condition is not met.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

reference is either the name of, or a pointer to, a vector, an array, or a
column of a table. It can be an expression that evaluates to the name or
pointer.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

number indicates the visual cue displayed in the pop-up window and whether the
message prefix, including the text "FTB", is displayed.

1         Information sign and message prefix
2         Warning sign and message prefix
3         Stop sign and message prefix
10001     Information sign, no message prefix
10002     Warning sign, no message prefix
10003     Stop sign, no message prefix


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

messagetext is the text of the message itself, and can be a text string,
variable, expression, or any combination of these.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

parameter is a value for a variable which can be included in the text of
messagetext. The values are separated by commas and substituted in the order in
which they are listed into place-holder underscore (_) or caret (^) characters
in the text. If messagetext is not present, the values of the variables are
listed in the order in which the variables occur in the ERROR statement.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

expression is a string which contains an ASL language expression.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

base is the base for the exponentiation. If base is not specified, base e
(2.718281828459) is assumed.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

expression is any number or numeric expression for the power to which base is
raised.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

string is a string containing trigger characters followed by the names of
global values. The names of the global values are returned in the result, and
all other characters are replaced by blanks.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

trigger is one or more SBCS characters, any of which can be used to trigger the
replacement of global values. If trigger is omitted, @ is assumed.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

number is the number for which the factorial is required. It should be an
integer greater than or equal to 0 and less than 70. Real numbers are
truncated.

NULLs produce NULL. Any other value produces an error.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

number is the message number to be placed in ERROR.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

fill optional fill text to be associated with ERROR.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

statementlist is one or more statements to be executed if the CASE expression
equals the value 0.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

ref is a one-dimensional array, or a column within a table.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

value is the value for which a position in the specified array is required.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

first The first element of the array within which the search is to be
performed. If first is not supplied, it defaults to 1. If first is greater than
last, then ref is searched in reverse order.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

last The last element of the array within which the search is to be performed.
If last is not supplied, it defaults to the number of elements in the array. If
last is less than first, then ref is searched in reverse order.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

compare specifies the type of find to be carried out, and can be any comparison
operator:

"<="    Less than or equal to
"<"     Less than
"\<"    Not less than
">="    Greater than or equal to
">"     Greater than
"\>"    Not greater than
"<>"    Not equal
"="     Equal (not case sensitive)
"\="    Not equal
"=="    Equal (case sensitive)
"\=="   Not equal (case sensitive).

The default value for compare is "=".


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

statementlist is a single statement or a block of statements. Any errors
arising in statementlist are ignored.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

location is the name of the location, with or without a trailing backslash (\).


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

filename is the name of the file.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

vectorin is the vector containing the values to be gathered.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

quantity is a vector with its elements corresponding to the values in vectorin.
These elements are used to produce sum, max, and min.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

unique is the vector into which the unique values are to be gathered.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

pos is a vector, each element of which contains a number giving the position of
the first occurrence (in vectorin) of the corresponding unique value in unique.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

count is a vector, each element of which contains a number corresponding to a
discrete value in unique. This is the number of times the unique value was
found in vectorin.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

sum is a vector containing numbers corresponding to the unique values from
vectorin. These numbers are an accumulation of the values in quantity
associated with the values in unique.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

max is a vector containing the maximum values found in quantity for each value
in unique.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

min is a vector containing the minimum values found in quantity for each value
in unique.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

name is the name of the global value


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

newvalue is a new value for the global. If this is used, the function returns
the value before it is changed.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

condition is any expression. The result of condition is tested as true
(nonzero) or false (zero).


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

The keyword THEN introduces the statement, or set of statements, to be executed
if condition is true. You can omit THEN, but your program is more readable if
you include it.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

statementlist1 is a statement or set of statements to be executed if the
condition is true.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

The keyword ELSE introduces statementlist2. statementlist2 is a statement or
set of statements to be executed if condition is false. You can omit the entire
ELSE block.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

condition is any expression.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

trueexpr is the expression returned if condition is true.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

falseexpr is the expression returned if condition is false.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

nullexpr is the expression returned if condition is NULL.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

order is the vector which holds the alternative sequence. INDEX places the
number of the first reordered row into the first element of order.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

column The columns, major to minor, to be indexed. To index a column in
descending order, prefix that column with a minus sign (-).

Up to 16 columns are allowed.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

reference is the vector, or table column.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

expression gives the number of the element to be inserted into the vector.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

value can be used to supply the value of the new element.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

expression1 gives up to 16 values of key columns, which are used to allocate
the row in the table. The other elements in the row are set to NULL values.
Keys must be enclosed in {} braces.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

reference is the vector, or table column.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

expression gives the number of the element to be inserted in the vector.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

value can be used to supply the value of the new element.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

expression1 gives up to 16 values of key columns, which are used to allocate
the row in the table. The other elements in the row are set to NULL values.
Keys must be enclosed in {} braces. can be used to supply the value of the new
element of the referenced column.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

string is the string to be operated on.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

number is the number of the loop to be iterated. Loops are numbered from the
inside outwards.  If it is omitted, ITERATE applies to the innermost loop.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

number is the number of the outermost DO ... END block to be terminated. DO ...
END blocks are numbered from the innermost block outwards, beginning with 1
(the default).


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

express can be a variable or a one-dimensional array.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

start is the first element of the array given by express that LENGTH() is to
test. The default is 1.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

end is the last element that LENGTH() is to test. The default is the last
element in express.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

sep if provided, prevents the function including trailing separators in the
count of characters.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

reference is the variable, array element, or attribute which is to take a new
value. It can be a simple name, a name subscripted by [ ] or { }, an indirect
reference, or an attribute of any of these.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

operator can be  =, indicating a simple assignment of an expression, or a
compound operation such as +=, indicating that expression is to be added to
reference. See Assignments for a full list of compound operators.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

expression gives the value to be assigned.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

routine is the name of a procedure or function to be called from the library.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

library_name is the name of the ASL library. The name must be a constant (not a
variable).


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

dll_name is the name of the Dynamic Link Library file. The name must be a
constant (not a variable).


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

location is the path where the REXX command files can be found, or is the name
of the REXX function library. The location must be a constant (not a variable).


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

routine is the name of one or more procedures and functions declared as
publicly available.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

procedure is the name of a procedure that can be called indirectly.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

expression is the number of new lines required in the output file, and sets the
COUNT attribute to that number. It can be omitted and has a default value of
one.

If specified, expression must evaluate to a positive integer less than 256.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

name is the fully qualified name.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

base is the base for the logarithm. If base is not specified, the base of
natural logarithms, e (2.718281828459), is assumed. If base is specified, it
must be greater than 1 and less than 10**28.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

expression is any number or numeric expression for which a logarithm is
required.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

expression consists of up to ten expressions of the same type (for example,
numeric, character, or date). The type of the first value sets the data type to
which the other expressions must conform.  If any of the other expressions is
of a different data type from this value, it is ignored and cannot be
converted.

A complete vector can be checked by referring to its dictionary entry using the
subscript [0].


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

messageid is the identifier of the message template to be used.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

parameter is the text to be inserted into the message template.

The message templates are as follows:

"FTB0001", "FTB10001" Progress message
"FTB0002", "FTB10002" Information message
"FTB0003", "FTB10003" Warning message

All message templates create a temporary window for displaying a message. The
templates with four-digit numbers display a message prefix, including the text
"FTB". The templates with five-digit numbers do not display the message prefix.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

expression consists of up to ten expressions of the same type (for example,
numeric, character, or date). The type of the first value sets the data type to
which the other expressions must conform. If any of the other expressions is of
a different data type from this value, it is ignored and cannot be converted.

A complete vector can be checked by referring to its dictionary entry using the
subscript [0].


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

object is the name of the object to be modified.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

att is an attribute that is to be modified.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

value is the new value for att.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

procedure is a reference to a procedure, with arguments if required.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

fullname is the fully qualified name.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

target is a variable which will be defined as a vector and which will contain a
list of names.  The meaning of these names depends on the string to the right
of the assignment, which can either contain an empty string, or the first or
second part of a two-part name.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

If there is an  empty_string to the right of the assignment, target will
contain a list of tables and objectstores which are currently open. This list
will not include memory datastores.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

objectstore_prefix is a string containing only one word (the objectstore name)
target will contain a list of data groups in that objectstore.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

objectstore_group is a string containing two words (which define the group)
joined by a period. target will contain a list of data items in that group.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

value is the value to be checked.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

statementlist is one or more statements to be executed if the CASE expression
returns a value of NULL.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

expression The value of expression is tested against a data type of NULL. If
the data type is NULL, a value of 1 (true) is returned. Otherwise, a value of 0
(false) is returned.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

event is the name of the event that triggers the block.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

parameter is a list of one or more variables that are associated with the
event.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

class is the object class of which this instance is a member. The object class
governs the attributes, actions, and events that the instance can have.

(See the sections on specific objects for details of the attributes, actions,
and events associated with each of these object classes.)


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

instance is the name of the object instance being created.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

parent is the parent of this instance, if there is one. The parent attribute of
the new object is set to this value. If the parent exists, the new object is
automatically closed when the parent is closed.

Some object classes expect a parent of a certain class. For example, a RADIO
object expects a parent of class WINDOW.

If parameter position is needed, the parameter for parent can be left blank as
in:

OPEN WINDOW main_entry,,"I.windows.basic_window",
     title="The main window",bgcolor="blue"

which opens a window and leaves the assignment of parentage to the system.
saved_object


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

saved_object is the name of an object that was previously saved. Specifying a
saved object means that the attribute values of that object are given to this
new object.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

attr is the name of one of the attributes of the class object.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

value is the value that attribute attr is to have when this instance of the
object class is created.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

proc is a reference to a procedure in this program that is to be called to
provide attribute values. The parentheses enclosing parms must be present even
if the parameter list itself is empty.

For details of individual objects that can be opened using the OPEN statement,
see Summary of objects.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

statementlist is a single statement or a set of statements to be executed if
the value of the CASE expression has not been identified by one of the
preceding clauses of the CASE statement. If OTHERWISE introduces more than one
statement, these statements must be enclosed in a DO...END block.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

target is the string onto which a new substring is to be overlaid.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

repstr is the new substring.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

num is number of the byte (counting from the beginning of target) at which
overlaying is to start. If num is omitted, overlaying starts at the first
character in target.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

len is the number of bytes of the target to be overlaid. The default is the
length of repstr.

If len is zero, repstr is inserted immediately before byte number num rather
than overlaying any part of target. If len is greater than the length of
repstr, repstr is not padded out to the right. Instead, the overlay still takes
place but excess characters up to len are removed. (This allows a short
substring to overlay a long substring.)


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

pad is the SBCS character used for padding target if the length of target is
less than num. Any pad parameter must be a single character. The default pad
character is a space.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

string is the string to be padded.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

length is the length to which string is to be extended with pad characters. If
length less than the original length of string, it will default to the actual
length. length should not be greater than the maximum system string length.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

type specifies how the padding is applied:

"L"   Leading - padding to the left of string
"T"   Trailing - padding to the right of string
"C"   Center - padding to both left and right of string.

Default: "L"


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

pad is the character to pad the string with. pad must be a one-character
string. The default pad character is a space.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

strip specifies whether leading or trailing blanks should be removed before
padding:

"B"   Both - leading and trailing spaces removed
"N"   None - no leading or trailing spaces removed
"L"   Leading - only leading spaces removed
"T"   Trailing - only trailing spaces removed.

Default: "B"


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

expression is the number of new pages required in the output file and sets the
COUNT attribute.  It can be omitted and has a default value of one. If
specified, expression must evaluate to a positive integer less than 256.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

string is a string for which a length in dialog units is required.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

window is an optional parameter that identifies a window.  PLENGTH() can then
return the correct value for a window that does not use the default system
font.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

varname is the name of the variable for which the pointer value is required.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

element1 is the element number within the target variable, if it is an array.
If element1 is not specified, then it defaults to 1.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

element2 is the second element number within the target variable, if it is a
two-dimensional array. If element2 is not specified, then it defaults to 1.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

expression is the number of the next position for output.

If the current position is already beyond the required position, no spaces will
be inserted. expression must evaluate to a positive integer.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

decimal_places is the number of decimal places used in the result of a
calculation.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

* means the maximum number of decimal_places available.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

procedure is the name to be associated with the statement or block of
statements which follows.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

parameter is a parameter which receives a value when the procedure is called or
invoked as a function. parameter is optional, and the enclosing brackets () can
be omitted if it is absent. Up to twenty parameters can be passed.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

procedurename is the name of the procedure for which a pointer is required.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

programalias is the alias name of the program to be queued for execution, as
provided by START.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

eventkeyword is the name of the event to be signaled . The default is QUEUE to
activate the ON QUEUE event block.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

parameter is a list of one or more parameters to be passed to the event
signaled.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

degrees is the value to be converted from degrees to radians.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

min is the minimum for the resulting pseudo-random number. If min is not
specified, 0 is assumed.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

max is the maximum for the resulting pseudo-random number. If max is not
specified, 999 is assumed.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

seed is the seed number on which the resulting pseudo-random number is based.
If seed is not specified, the previous result of RANDOM() is used as the seed.
If RANDOM() is used for the first time in a task, and seed is not specified, a
value based on the current time is used.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

oldname is the original variable reference.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

newname is the new variable reference.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

string is a string containing trigger characters followed by the names of
global values. The names of the global values are replaced with the actual
global values.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

trigger is one or more SBCS characters, any of which can be used to trigger the
replacement of global values. If trigger is omitted, @ is assumed.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

expression gives the value to be returned.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

expression provides the value to be converted.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

variable is a variable, the data type of which is to be adopted by the value of
expression.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

string is the string to be operated on.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

reference contains the column in the table, and one or more values of the
table's key columns in braces.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

condition controls what is done if the row is not found:

"="  Returns 0 if the matching row is not found
">=" If the row does not exist, returns the position at which the row would
     appear if it were to be inserted.

The default value for condition is "=".


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

programalias is the alias name of the program to be run.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

eventkeyword is the name of the event to be signaled. The default is QUEUE to
activate the ON QUEUE event block.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

parameter is a list of one or more parameters to be passed to the event
signaled.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

expression1 is a character string to be scanned.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

expression2 is a string of one or more characters which are to be tested for
within expression1.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

start is the character position within expression1 from which the scan is to
start. The default for start is 1, the first character position.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

end is the character position within expression1 at which the scan is to end.
The default for end is the final character position.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

compare specifies the type of scan to be carried out. It can be one of the
comparison operators:

"="     Search for the first occurrence of expression2 in expression1. Case of
        characters is ignored for SBCS. With DBCS, the characters are compared
        on a case-sensitive basis.

"\="    Search for the first nonoccurrence of expression2 in expression1. Case
        of characters is ignored for SBCS. With DBCS, the characters are
        compared on a case-sensitive basis.

"=="    Search for the first occurrence of expression2 in expression1.
        Characters are compared on a case-sensitive basis.

"\=="   Search for the first nonoccurrence of expression2 in expression1.
        Characters are compared on a case-sensitive basis.

The default comparison operator is  "=".


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

type specifies the type of comparison to be performed:

"*"  Search expression1 for the entire string in expression2

"1"  Search expression1 for any character in expression2.

The default for type is "*".


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

string is any string. If string is the only parameter supplied, or if number is
not supplied, the function returns the number of separate items in the string.
An empty string ( "") produces a result of zero.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

number is a number. If number is specified, then SEPARATE() returns that item
in the string. Otherwise it returns the number of items in the string. If the
value of number exceeds the number of items in the string, then SEPARATE()
returns an empty string ( "").


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

separator is the separator character used to separate the words in string. The
default separator character is a space.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

instance is the instance of the object to be closed.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

programalias is the alias name of the program to be signaled.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

angle is the angle for which the sine is required.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

frequency can be either a value in hertz (cycles per second) between 36 and
15000, or a value in the range 1-5 corresponding to the following preset notes:

1  220 Hz
2  440 Hz
3  880 Hz
4  1760 Hz
5  3520 Hz

If frequency is specified in the range 6-35 Hz, then no note is produced, but
there is a delay (pause) of the specified duration.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

duration is the duration of the note in tenths of a second. The default value
for duration is 1 (one tenth of a second).


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

expression is the number of space or blank characters required in the output
file.  This sets the COUNT attribute to that number. It can be omitted and has
a default value of one. If specified, expression must evaluate to a positive
integer which is in the range 0-255.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

expression gives a value to be split.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

start is the character position within expression from which the split is to
start (that is, the part to be extracted starts at this character position).
start must be an integer or a real number.  (Real numbers are truncated.)


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

length gives the number of characters to be split off, or extracted. length is
optional. If length is omitted, the default value is from start to the end of
the string.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

fill specifies the filler character. The filler character is any character
which, when present, is used to pad out the extracted part to the value of
length if there are not enough input characters. This would happen if the
number of characters between start and the end of expression is less than the
specified length. When an align parameter is present, fill defaults to a blank
(" "). fill only pads up to the maximum string length.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

align specifies how the extracted characters are placed in the output string,
assuming padding occurs.

The values permitted for align are:

"L"   Left justify (Default)
"R"   Right justify


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

expression yields a value for which a square root is required.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

tasktype can be APPLICATION, MASTER, or PROGRAM.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

programalias is the name by which the program is referred to in later RUN or
QUEUE statements. programalias must be a simple variable or an array element
and is set by the START statement.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

modulename is the name of the module which is to be RUN.

The second occurrence of the keyword START is optional. Its inclusion allows
parameters to be passed to the ON START block of the program being started.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

parameter is a list of one or more parameters to be passed to the ON START
block. A maximum of ten parameters can be passed.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

array is a one-dimensional or two-dimensional array.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

text is a text string which forms a template for the result. It can also be the
name of a variable containing a string, or a concatenation of values.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

text can contain underscore (_) or caret (^) characters. These are replaced in
the string by expression (and any subsequent expressions). A maximum of nine
expressions can be used.

Underscore inserts the expression into text without quotation marks. Caret
causes the expression to be surrounded by single quotation marks before it is
inserted.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

expression is the number of tab characters to insert.

If the current position is already beyond the required position, no spaces will
be inserted. expression must evaluate to a positive integer.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

angle is the angle for which the tangent is required.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

number is the number of the repeating block to be terminated. Blocks are
numbered from the innermost outwards, beginning with 1. Nonrepeating blocks are
excluded from the count.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

THEN The keyword THEN introduces a list of one or more statements to be
executed if the condition is met. THEN can be omitted, but including it can
make a program more readable.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

statementlist is a statement or a set of statements to be executed if the
condition (IF statement) is met.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

expression is the value to be converted.

Optional, defaults to current time.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

format is the format which describes the time.  If it is omitted, the default
time format is used.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

expression expression and subsequent expressions can be numeric values or
expressions producing numeric values. A complete vector can be checked by
referring to its dictionary entry using the subscript [0]. A TOTAL() function
can include up to ten expressions.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

ON Starts a trace of all Visualizer statements as they are executed.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

OFF Turns off tracing.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

LINE Traces only the line numbers of these statements.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

BRANCH Traces only statements which change the flow of control through the
program.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

string is the string to be trimmed.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

type specifies whether leading or trailing blanks should be removed:

"B"   Both - leading and trailing spaces removed
"N"   Neither - no leading or trailing spaces removed
"L"   Leading - only leading spaces removed
"T"   Trailing - only trailing spaces removed.

Default: "B"


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

statementlist is one or more statements to be executed if the CASE expression
returns a value which is nonzero.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

stem is a string. If stem is included, the new string returned starts with
stem. If stem is omitted, the default stem "FTB__" is used.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

length is the length of the string including the stem. If length is omitted, it
defaults to the maximum length of names (20).


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

expression is the condition to be tested.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

statementlist is a statement or a set of statements executed repeatedly until
the condition specified in expression is met.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

string is the string to be converted to uppercase.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

value represents a value to be checked. A complete vector can be checked by
referring to its dictionary entry using the subscript [0]. The function accepts
up to nine values.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

array is a one-dimensional or two-dimensional array.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

ref is the vector to be verified.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

content is a variable whose content (and format in the case of dates and times)
is used to check ref.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

start is the element position within ref from which the check is to start. The
default for start is 1.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

end is the element position within ref at which the check is to end. The
default for end is the final element position.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

compare is the type of verification applied:

"="   ref is the same type as content or can be converted to the same type.

"=="  ref is the same type as content.

      No automatic conversion is carried out.

"\="  ref is unequal to content.

"\==" ref is unequal to content and cannot be converted to that content.

The default value for compare is =.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

null If specified as 1 (true), causes VERIFY() to ignore NULL elements.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

programalias is the alias name of the program to wait for.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

expression is a potential value of the expression presented by the CASE
statement. expression can be a simple value or a complex expression which
includes operators.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

statementlist is one or more statements to be executed if the CASE expression
equals the value given by WHEN expression.

A WHEN statement can control a single statement or a set of statements. A set
of statements must be enclosed in a DO...END block.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

expression is the condition to be tested.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

statementlist is a single statement, or a set of statements contained in a
DO...END block. statementlist is executed repeatedly if and as long as the
condition specified in expression is met.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

string is the string to be tested (in quotes).


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

number is the number of the character required (if the nth character is a
separator, the previous word position will be returned).


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

separator is the separator to be used. The default separator is a space.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

string is the string to be operated on.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

number if supplied, specifies the number of the word to be returned from the
string or the word at the beginning of a phrase to be returned.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

sep is the character to be used as separator. Any separator used must be a
one-character string. DBCS characters cannot be used. The default separator is
a space.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

length is the total number of words in a phrase to be returned from the string.