accell/sql: script and function reference

ACCELL/SQL:Script and Function Reference

�

2

�� !�"�� !

#�� $�� $�� $��$�� $�� $��%��%��$��%�� !

� �� &�� %�� %�� $�� %�� $��$��!�'$�� $�� &�� %��$�� $�� !

(��%�� $�� $� �� $ ��%��)�� !(��%��$�� %�� !�*�� %��%�� &�� $�� $�� !

� �� $�� $�� $�� $��

��$�� !�"�� +

"�� $��,� �� -�$�� !�� .��/0��1�2��/�03/��1��32��03/'�4�1��32��03/3

�#*'5��6))��7*�*8#�� )�� &�� !��

9�� &�� !��#*4�� &��8�� :��$��

�� $ ��!�(��4�;� �%�� $��,��$��* ��$��

(�� !�,��8�'�� 8�'<,�� &��8�� %��'�$ �� * �!��5-��6��

�� &�� =)��9->)�� 8�� &��* �!*#'8?,*4�� &��* ��@��%��* �!��$�� *-,!�*#:?6��

�� &��$��* �� * �!�8?��)6�� &��8��

�� !��$ �� &�� $ 7��%��$ >��$ >/��4��<#�;��$ 8��"�>#'��

8�� ;� �%�� &��$ �,��!��"�?�� &�� &��

�� &��"�?��* �� * �!��"�?�� @��$��$ �,��* �!

#�� &��#��* �!�,�� &��$��* �!,��,��,�>98�� ;� �%�� &��,�� !��

�� $�� &�� &��&��

�� $��$�� A�� !

"��#$��+�B�3�>/

3

��

��

��

�� !��"�� #��

��

��$%%&�'%��(�� )��

��$%%&�*%�$��"�� ++�� "��,��-��"�� ++�� ,��-��"�� +��

,��-��"��-�� +#��

.��(��-�� +)��

��-�,��"�� /��

��-�0��( �� 1��

�� 2�� ,��"�� #��

��$%%&�*%�,��-��"�� 3��$��"�� 3��-�� 3��-�,��"�� 0��( �� 4��"�� 4��

��! �"��

��$%%5�6�$ ��7�8 ��..5�%%�9$. �+��.5��7�8 �+��.5%�:$% ��.5�85$8�!6 ��5��$�� 5��7� �1��5$.7� �1��5,78. �#��5;�� 3��

4

:%78< �3��:��8.$. �4��$5��80$!�7�8 �)��%$�!5�..5$=� 1/��%$�!5�,�$!5�� 1/��%$�!5,78.5$=� 1��%7�<5�85,7$%. 1+��% 1��%5�!7*78 1��%�8578.$= 1��%�85%�9$!5:��8.� 1��%�85��$!5:��8.� 11��!5,7$%. 11��!58$=�5,7$%. 1#��.��5�6�$ 13��.:5%$8*�> 13��.:5�6�$ 14��.$%$�$5�%%�9$. 14��.7$8�7�8 1)��.7��%�65,�!�� 1)��.7��%�65?��7,6 #/��$�>�$. #/��$��7��$.5��8� #��,7$%.5%$8*�> #��,7$%.58�$ #+��,7%$5��> #+��,78.5��7�8 #��,78.5�%%�9$. #��,78.5��8� #��,78.5%�:$% #1��,78.�:%$ #1��,7!��5,7$%. ##��,�!58�$ #3��,675$��*$ #3��>$7*>� #4��>$%�5�!�>70$ #4��>$%�5,�!5��% #)��>$%�5,�!58�$ #)��>$%�5,�!5!�9 3/��785$�!6 3/��%�:$% 3��%7��578.$= 3��%7��5%�9$!5:��8.� 3+��

5

%7��5��$!5:��8.� 3+��%�9578�$8�7�6 3��$8�5%�:$% 3��%�750�%�$. 3��8$=�5,7$%. 31��!!$8�$� 3#��!$05,7$%. 3#��!$05,�! 33��!$'�7!$. 33��!$�!7$0$50�%�$ 34��!$0$!�$ 3)��!�9 3)��!�9578.$= 4/��!�95%�9$!5:��8.� 4/��!�95�!7*78 4��!�95��$!5:��8.� 4��$�!�>5!�8*$� 4+��$%$��$.5�$�5��!�%%:�! 4��'%5��%�85��8.7�7�8 41��'%5��7�8�%5��8.7�7�8 41��'%5�!.$!5:65�%��$ 4#��'%5�!.$!5:65��%�8 4#��'%59>$!$5�%��$ 44��5,�!578�� 44��:5�� 4)��!*$�5,7$%. 4)��!*$�5��:%$ )/��8.$!%78$ )/��.��$5��%%�9$. )��.��$�:%$ )��$5:��$5978.�9 )+��97.�> )+��978.�95>$7*>� )��978.�9597.�> )��

��!��#�$�� "%��

�,�$!��.. )3��

�,�$!��%7��7�8 )4��

�,�$!�.$%$�$ �//��

�,�$!�,7$%. �/��

�,�$!�,78. �/��

6

�,�$!�,�!�!$��!8 �/1��

�,�$!��.��$ �/3��

�,�$!�;�� /)��

�%�$!��>$� ��

�%�$!��:%$ ��+��

��%7��7�8 ��

:$,�!$��.. ��4��

:$,�!$��%7��7�8 ��)��

:$,�!$�.$%$�$ �+/��

:$,�!$�,7$%. �+��

:$,�!$�,78. �+��

:$,�!$�,�! �+1��

:$,�!$�!$��!. �+#��

:$,�!$��.��$ �+3��

:$*785�'% �+)��

:$*78�9�!< ��

:!$�< ��

:!$�<��78� ��1��

�>�8*$��!!$8��!$��!. ��3��

�>��$�,7!��,�! ��4��

�>��$�8$=��,�! ��

�%$�!��8.�'�$�$ ��#��

�%$�!��.. ��3��

�%��$��7�$%78$ ��4��

��7��9�!< ��)��

��8�78�$ �1��

�!$��$��7�$%78$ �1��

�!$��$��>$� �11��

�!$��$��:%$ �1#��

�!$��$��7$!�$0$8� �13��

�!$��$�07$9 �#/��

.$,78$��8. �#��

.$78��%% �#4��

7

.$%$�$ �#)��

.$%$�$��!!$8��!$��!. �3+��

.$%$�$��$%$��$.�!�9 �3��

.$%$�$��7$!�$0$8� �31��

.7��:%$�;�� 3#��

.7��%�6 �33��

.7��%�6�>$%� �4��

.7��%�6��!7 �4��

.!��>$� �41��

.!��:%$ �4#��

.!��07$9 �43��

$8�:%$�;�� 44��

$8.5�'% �)+��

$!��$�>$%� �)��

$!��$��!7 �)1��

$=$��78* �)3��

$=7� +//��

$=�$!8 +/��

,7$%. +/1��

,�! +/4��

,�! +�/��

,�8��7�8 +�#��

*!�8� ++��

7, ++��

787��,7$%. ++1��

78�� ++3��

78�$!� ++)��

78��%% +�+��

8$=��7�8 +��

�8��%$�!��.. +�4��

�8��%$�!��,78. +�/��

�8�$=7� +�+��

�8�,7$%. +�1��

8

�8�,78. +�3��

�8�8$=��,�! +�)��

�8�8$=��!$��!. +1��

�8��!$07��,�! +1��

�8��!$07��!$��!. +11��

'�$�$��8. +13��

!$,!$�>��!$$8 +1)��

!$?$��$!��7�8 +#/��

!$?$��!$��!. +#��

!$��78��!$$8 +#��

!$�$�� +#1��

!$��!��8�,7$%. +#3��

!$��!��= +#)��

!$�!7$0$ +3/��

!$��!8 +3��

!$0�<$ +3��

!�%%:��<�9�!< +31��

�$%$�� +33��

�$� +4��

�$��8. +4)��

�%��< +)1��

��!$ +)4��

�97��> �//��

�8%��< �/��

��.��$ �/#��

��.��$��!!$8��!$��!. ��/��

��.��$��$%$��$.�!�9 ��+��

9>$8�,7$%.��>�8*$� ��1��

9>7%$ ��3��

9!7�$��7�$%78$ ��)��

=%��< �++��

;��!$��!8�0�%�$� �+1��

�!��&�'�� ( ��

9

� 5� �@� A �+)��

�� 5-� �ABCD ��

(�"E�� ABCD ��+��

(��ABCD ��

(�� ABCD ��1��

"��5�"�-�ABCD ��#��

"��5"� �5��5��ABCD ��/��

"�"E5 ��ABCD ��

" ��5��ABCD ��

" ��5-��52� �ABCD ��1��

"��5 ��ABCD ��#��

"��5��"�� 5"��ABCD ��3��

"��5��"�� 5��-ABCD ��4��

"��5��-�ABCD ��)��

��5��5- �ABCD �1/��

(5��ABCD �1��

(-�5��ABCD �1+��

(-�5��5�ABCD �1��

� ��5� �@� A �11��

�-�5��"�ABCD �13��

�� "��5-� �ABCD �14��

2�� 5� �@� A �#/��

2 ��5��5 ��EABCD �#+��

2��5��2��5-� �ABCD �#��

��5 �2�� 5�"�-�ABCD �##��

��5 ��5�25��ABCD �#3��

��5-��ABCD �#4��

��5��@�� ABCD �3/��

��ABCD �3+��

� �(5��5"�-��ABCD �3��

��5� ABCD �33��

��5��-�ABCD �34��

��2�5 �� A �3)��

10

��5"��5��"�� 5�� ABCD �4/��

5� �@5��ABCD �4+��

5@��5��-�ABCD �4��

��5"�--�� ABCD �4#��

��5"�--�� 5��-�ABCD �44��

- �5��5 ��ABCD �)/��

�� 5"��ABCD �)+��

��5-��52� �ABCD �)��

��5��ABCD �)#��

�� 5��5 �2�ABCD �)3��

�� 5��5��ABCD �))��

��5�� ABCD �/��

��"�� 5��5"��ABCD �/+��

��5��5��5"�-��ABCD �/��

��5-��ABCD �/3��

��5(��5"� ��AB�D ��

��5"��5-�-5 �-��ABCD ��

��52�� 5"� ��AB�D ��#��

��5��ABCD ��)��

��@5 ��ABCD �+/��

� ��ABCD �+��

��5"�-��AB�D �+��

��5��AB�D �+#��

��5�� "�AB�D �+)��

�� 5" ��ABCD ��

�� 5"� �ABCD ��+��

�� 5��-��ABCD ��

�� 5��-��5"��ABCD ��

�� 5��-��5�ABCD ��1��

�� 5��ABCD ��3��

��ABCD ��4��

��5��5"��5"� �ABCD ��1��

��5��5 ��ABCD ��#��

11

��5��5��-�ABCD ��3��

��5��5�� ABCD ��4��

�� ABCD �1/��

��((��ABCD �1+��

��(��ABCD �1��

��-ABCD �11��

��5�-��ABCD �1#��

��5(��ABCD �13��

��5(�� ABCD �14��

��5 ��ABCD �1)��

��52 ��ABCD �#/��

��5��-ABCD �#��

��5��ABCD �#+��

��5��5��ABCD �#��

��5��ABCD �##��

��5��-�ABCD �#3��

��5�� ABCD �#4��

��5-� �ABCD �#)��

��5��ABCD �3��

�� 5� �@� A �3��

��5� ABCD �31��

��5��-�ABCD �3#��

�� 5��5��ABCD �33��

��ABCD �3)��

)��&�*��&�� +��

��" (@BCD �4��

��" "2 BCD �41��

��" (� BCD �43��

��" (�BCD �4)��

��" 2��-BCD �)��

��" �BCD �)��

��" �� BCD �)#��

��" �@� B�D �))��

12

��" ��BCD 1//��

��" @�BCD 1/+��

��" @� BCD 1/��

��&�#�� %, ��

��&�#��-��.��/��0�&�1��&� %,"��

��&�#�2-��#�� %�%��

��! %� ��

13

��

This manual is one of a set that describes the ACCELL/SQL applicationdevelopment system. This manual, �� , gives complete syntax descriptions and examples of allACCELL/4GL script statements. Use this manual with its companionmanual, �� , which describes theACCELL/4GL component and how to create form scripts.

This manual is intended primarily for the application developer.Throughout this manual, the word you refers to the application developer.The word user refers to any person who will be using your completedACCELL/SQL application.

Before using this manual, become familiar with the basic manuals of theACCELL/SQL set. Each manual is written for a specific user or for aparticular step in the application development process.

Prerequisite Manuals

The following manuals contain procedures and information that areessential to understanding how form scripts are used:

��

Optional Manuals

This manual describes the ACCELL/4GL language for character modeapplications. For additional information about how to create applicationsin a graphical presentation mode, use this manual with the graphical userinterface manual:

�� !��" �� #��

Using This Manual

14

In some cases, ACCELL/SQL works differently depending on therelational database management (RDBMS) system that is used with it.ACCELL/4GL statements that are customized to the RDBMS areindicated by the phrase “RDBMS dependent” at the beginning of eachsyntax description. For additional information about how ACCELL/SQLinteracts with the RDBMS, see the manual that describes RDBMSintegration:

��$%�#��

For information about how to create form scripts that can be adapted toany type of RDBMS, see ��&��' � �(!� �� .

Some ACCELL/4GL statements are provided for use with ACCELL/SQLInteractive Debugger, an optional product that is available separately. Ifyou are using this product, refer to ��#�� '��)�� for complete information.

This manual uses the following syntax conventions to describeACCELL/SQL statements and functions:

Intersecting circles indicate that the statement hascapabilities that are dependent upon a particularoperating system, user interface, or RDBMS. Extensionsor conditions and restrictions are described in the“Support” section that appears below the syntaxdescription. For more information about RDBMSdependencies, see ��$%�#�� .For information about graphical user interfacedependencies, see �� !��" �� #��.

boldface Boldface words are literal strings that you must typeexactly as shown.

italic words Italic words indicate arguments, variables, numbers, orexpressions that you must provide. Examples are tablenames, column names, and constants. Titles of manualsare shown in italics, for example, �� .

SyntaxConventions

15

Shaded areas in syntax descriptions indicate features thatare restricted to a particular user interface, operatingsystem, or RDBMS.

UPPERCASE Boldface UPPERCASE words in syntax descriptions areACCELL/SQL reserved keywords. ACCELL/SQLkeywords are not case sensitive: you can type eitheruppercase or lowercase letters.

UPPERCASE Italic UPPERCASE words represent ACCELL/SQLconfiguration variables.

UPPERCASE Other UPPERCASE words represent ACCELL/SQL datatypes, such as FLOAT and TEXT.

( ) Parentheses enclosing an item in the syntax indicate thatseveral elements make up a single item. If theparentheses are in boldface type, they are part of thesyntax and must be included.

[ ] Square brackets indicate that the enclosed word or itemis optional and may be left out. If the brackets are inboldface type, they are part of the syntax and must beincluded.

|| Vertical bars enclosing a stacked list of options mean thatyou can choose one of the listed options, but only one ofthem.

. . . Ellipsis points indicate that you can repeat theimmediately preceding item any number of times, asneeded.

“Title” Chapter and section titles are enclosed by a pair ofquotation marks.

”variable” The name of a developer-defined variable can beenclosed by a pair of quotation marks. Variable namesare case sensitive: uppercase and lowercase letters arenot equivalent. For example, ”company_address” and”Company_Address” are two different variables.

16

$variable A dollar sign ($) prefix identifies a variable name.

function$ All ACCELL/SQL system functions are suffixed by adollar sign ($). The dollar sign distinguishes anACCELL/SQL function from a developer-definedfunction. Do not include a dollar sign when you call yourown functions.

Words that appear in bold, italic, sans-serif typeface indicateACCELL/SQL commands that the user can execute from the keyboard, forexample:

Press ��.

The specific keys vary depending upon the user’s terminal and the systemconfiguration. Because of the flexibility of ACCELL/SQL, you can assigncommands to different function keys, for instance, �� . Somecommands can be executed by using escape sequences or control keys.For information about configuring ACCELL/SQL commands, seeACCELL/SQL: Configuring Applications.

For information about operating system, user interface, and RDBMSdependencies, see the appropriate ACCELL/SQL manuals listed in the SeeAlso section of each syntax description. In addition, the following booksmay also be useful:

Nye, Adrian, and Tim O’Reilly. X Toolkit Intrinsics ProgrammingManual for Version 11 of the X Window System. Volume4 of the X Window System series. Sebastopol, Calif.:O’Reilly & Associates, 1990.

OSF/Motif Programmer’s Reference: Quest Motif Environment. SantaClara, Calif.: Quest Systems Corporation, 1991.

Quercia, Valerie, and Tim O’Reilly. X Window System User’s Guide forX11 R3 and R4. Volume 3 of the X Window Systemseries. Sebastopol, Calif.: O’Reilly & Associates, 1990.

X Toolkit Intrinsics Reference Manual for X Version 11. Edited by TimO’Reilly. Volume 5 of the X Window System series.Sebastopol, Calif.: O’Reilly & Associates, 1990.

AdditionalResources

17

ACCELL/4GL FormScript Elements

18 ACCELL/4GL Form Script Elements

��

This chapter lists the elements of an ACCELL/4GL form script accordingto categories. Elements are categorized into these sections:

ACCELL/SQL attributes

ACCELL/4GL event sections

form script statements

database statements

system functions

system variables

predefined C functions

The last section of this chapter describes general ACCELL/4GL formscript conventions.

19ACCELL/4GL Form Script Elements

ACCELL/SQL Attributes

This section lists all ACCELL/SQL attributes for character modeapplications. Default attributes are set in ACCELL/Generator but can bechanged by an ACCELL/4GL form script. Read-only attributes can betested or used as values in scripts.

For complete descriptions of all ACCELL/SQL attributes, see the“Attributes Summary” chapter of this manual.

��

Type Settable in ACCELL/4GL Readable Only

Boolean ADD_ALLOWEDAUD_ON_ENTRYAUTO_COMMITAUTO_FINDCLEAR_AFTER_AUDELETE_ALLOWEDFIND_ALLOWEDUPDATE_ALLOWED

CLICK_ON_FIELDUSE_BASE_WINDOW

Numeric FIND_COUNTFIRST_FIELD

COL_ORIGINHEIGHTOCCURRENCESROW_ORIGINWIDTH

String CUR_NEXT_FIELDSQL_OPTIONAL_CONDITIONSQL_ORDER_BY_CLAUSESQL_ORDER_BY_COLUMN

CUR_FIELDFORM_NAMEMENU_LABELPREV_FIELDPREV_FORMSELECTED_SET_SCROLLBARSQL_WHERE_CLAUSETARGET_TABLE


��


Boolean IN_MEMORY

String ACCELL_TYPEFILE_PATH

Misc. CLEAR_ADD_EXP

��


Boolean AUTO_ACCEPTAUTO_EDITAUTO_ZOOMBLINKECHOEDFINDABLELOW_INTENSITYREQUIREDREVERSESTOP_FOR_INPUTTAB_STOPUNDERLINEUPDATEABLE

MULTI_VALUED

Numeric COLHELP_FORM_COLHELP_FORM_ROWROWWINDOW_HEIGHTWINDOW_WIDTH

FIELD_LENGTH

String CASE_CONVERSIONDISPLAY_FORMATDISPLAY_JUSTIFYFYI_MESSAGEHELP_ARCHIVEHELP_FORM_NAMENEXT_FIELD

DATA_TYPEFIELD_NAME


��


Boolean RETRIEVE_VALUE

String SEARCH_RANGESSQL_COLUMN_CONDITION

DB_LENGTHDB_TYPETARGET_FIELD

Expres-sion

CLEAR_FIND_EXP

��

Type Settable in ACCELL/4GL

Action ACTIONAUD_ACTIONFIND_ACTION

String AUD_LABELFIND_LABELLABEL

��

Type Readable Only

Boolean BOUNDED

Numeric COLUMN_INDEXCOLUMN_LOWER_BOUNDSCOLUMN_UPPER_BOUNDSESTIMATED_COUNTLIST_INDEXLIST_LOWER_BOUNDSLIST_UPPER_BOUNDSROW_INDEXROW_LOWER_BOUNDSROW_UPPER_BOUNDS

String DIMENSION


ACCELL/4GL Event Sections

ACCELL/4GL execution is event driven. A command executed by the usercauses an event section to be executed; the event determines thestatements that will be executed. ACCELL/4GL event sections aredescriptions of the events. An event section tells ACCELL/Manager whento perform the associated statements.

The ACCELL/4GL event sections are divided into groups:

master application form sections

standard form sections

All event sections that can be used in a master application form script arelisted under “Master Application Form Sections” in this chapter. Thelisting includes both those sections that can only be used only in a masterapplication form script and those that can be used in both types of formscripts.

All event sections that can be used in a standard form script are listedunder “Standard Form Sections” in this chapter. “Standard FormSections” groups the sections by the type of action they perform. Thislisting includes both those sections that can be used only in a standardform script and those that can be used in both types of form scripts.

The master application form sections are the ACCELL/4GL sections thatare valid in a master application form script. The master application formis the first form executed in an application and is the form that initializesthe application. There is only one master application form per applicationand it must be included in the application.

Master application form sections fall into three categories. As shown inthe following table, some sections are optional and others are required.Some can be used only in a master application form script, and others canbe used in both master application and standard form scripts.

Master ApplicationForm Sections


��

Category Description Event Section

ApplicationHeader

RequiredDefines the application

APPLICATION

ApplicationSections

OptionalValid only in a masterapplication form script

BEFORE APPLICATIONAFTER APPLICATIONCHOOSE FIRST FORM

Other ValidSections

OptionalValid in both masterapplication and standard formscripts

AFTER FIELDAFTER FORM RETURNAFTER ZOOMBEFORE FIELDBEFORE FORMDEFINE COMMANDFIELDINIT FIELDON CLEAR TO ADDON EXITON FIELDON NEXT FORMON PREVIOUS FORMWHEN FIELD CHANGES

Standard form sections are the event sections that are valid in a standardform script. If a standard form has a target table defined, it can performinteractive database operations.

The standard application form sections fall into five categories. As shownin the following table, some sections are optional and others are required.Some can be used only in a standard application form script, and otherscan be used in both master application and standard form scripts.

Standard FormSections


��

Category Description Event Section

StandardFormHeader

RequiredDefines the ACCELL/SQLform script.

FORM

FormSections

OptionalMost of these sections arevalid in master applicationand standard form scripts.

AFTER FORM RETURNAFTER ZOOMBEFORE FORMCHOOSE NEXT FORMON EXITON NEXT FORMON PREVIOUS FORM

Find, Add,Update, andDeleteSections

OptionalThese sections are valid onlyin a standard form scriptbecause they require a targettable.

Find Sections:AFTER FINDBEFORE FINDON CLEAR TO FINDON FIND

Add Sections:AFTER ADDBEFORE ADDON CLEAR TO ADDUpdate Sections:AFTER UPDATEBEFORE UPDATE

Delete Sections:AFTER DELETEBEFORE DELETE

RecordSections

OptionalThese sections are valid onlyin a standard form scriptbecause they require a targettable.

BEFORE RECORDON NEXT RECORDON PREVIOUS RECORD

FieldSections

OptionalThese sections are valid inboth master application formand standard form scripts.

AFTER FIELDBEFORE FIELDFIELDINIT FIELDON FIELDWHEN FIELD CHANGES


Category Event SectionDescription

CommandExecutionSection

OptionalThis section is valid in bothmaster application andstandard form scripts.

DEFINE COMMAND


Form Script Statements

ACCELL/4GL event sections contain form script statements. Statementsdefine the tasks to be executed by ACCELL/Manager. When an eventoccurs, ACCELL/Manager locates the associated event section andexecutes the statements sequentially. ACCELL/4GL statements can bedivided into seven categories, as described in the following table.

ACCELL/4GL Statements

Category Description Statements

Assignment Assign values toACCELL/SQL variables andattributes.

SETSET COMMAND

CommandExecution

Provide the ability to executedefined commands and timerfunctions.

CLEAR COMMANDQUEUECREATE TIMER EVENTDELETE TIMER EVENTQUEUE COMMAND

Debugging Used with �� .

BREAKPOINT

Function Provide the ability to defineyour own functions written inACCELL/4GL. You can callthese functions from within aform script. You can writethese functions in either the Cprogramming language or inACCELL/4GL.

DEINSTALLEXTERNFUNCTIONINSTALLRETURN

(continued on next page)


ACCELL/4GL Statements (continued)

Category StatementsDescription

Input/Output

Provide the ability to acceptand output data.

Input Statements: INPUTRETRIEVE

Output Statements:CLOSE PIPELINECREATE PIPELINEDISPLAYSTOREWRITE PIPELINE

Screen Control Statements:DISPLAY HELPDISPLAY TRIMERASE HELPERASE TRIMREFRESH SCREENREPAINT SCREEN

Target Table Provide access to the databasefrom within a form script.You can select, add, updateand delete rows from databasetables. For multi-userapplications, you can alsocontrol locking of tables androws.

Selection Statements:EXECUTINGREJECT RECORD

Update Statement:UPDATE CURRENT RECORD

Delete Statement:DELETE CURRENT RECORD

Transaction Statements:BEGIN WORKCOMMIT WORKRESTART TXROLLBACK WORK

SQL Block Statements:BEGIN_SQLEND_SQL



ACCELL/4GL Statements (continued)

Category StatementsDescription

Control Provide the ability to controlthe flow of form statements.

Decision Statements:IFSWITCH

Repetition Statements:FORREPEATWHILE

Control Break Statements:BREAKCHANGE CURRENT RECORDCLEAR TO ADDCONTINUEEXITNEXT ACTIONREJECT OPERATIONRESTART ON FIELD

Form Sequence ControlStatements: CHOOSE FIRST FORM*CHOOSE NEXT FORM*ENABLE ZOOMDISABLE ZOOMZOOM RETURN VALUES

* This statement is also an event section.


Database Statements

The following database statements can be used in your form scripts in thesame way you use ACCELL/4GL statements. All database statementsmust be terminated by a semicolon (;).

�� !��""#�$"

Category Description Statements

SQL DDL Data definition language.Defines database objects andtheir relationships in thedatabase. DDL also includesstatements for removingobjects.

ALTER SCHEMAALTER TABLECREATE SCHEMACREATE TABLECREATE VIEWDROP SCHEMADROP TABLEDROP VIEWGRANTREVOKE

SQL DML Data manipulation language.Used to add, modify, or deletedatabase records.

DELETEINSERTSELECTUPDATE

ACCELL/4GL

Special ACCELL/4GLstatements that are preparedfor execution by the database.

DELETE SELECTEDROWUPDATE SELECTEDROWSLOCKUNLOCKXLOCK

You can also use other SQL statements provided by your RDBMS byenclosing them within a BEGIN_SQL and END_SQL statement block.

Additional HelpAll SQL statements must conform to the requirements of the RDBMS; thesyntax descriptions given in this manual are based on the ANSI standardfor SQL. For complete syntax descriptions of SQL statements, refer to thedocumentation provided by the RDBMS vendor.


System Functions

ACCELL/4GL system functions perform tasks such as file access, stringmanipulation, and status checking. You can call these functions directlyfrom within a form script.

System Functions

Category Description Function

ProcessControl

Control operating systemprocesses.

background$( )flush_to_disk$( )push_shell$( )serve_message$( )set_cursor_mem_limit$( )sleep$( )sql_clear$( )system$( )

BinaryManipula-tion

Extract binary data. binarylen$( )subbinary$( )

MessageFiles

Open, close, and retrievemessages from a custommessage file.

close_message_file$( )get_message$( )open_message_file$( )

ScreenInput/Output

Notify the user of a condition. beep$( )yesno$( )

StringManipula-tion

Clip, pad, compare, andconvert strings.

clip_str$( )pad_str_left$( )pad_str_right$( )strlen$( )substr$( )



System Functions (continued)

Category FunctionDescription

TextManipula-tion

Extract text. get_line_of_text$( )substr$( )





TypeConversion

Convert a variable from onetype to another.

STRING Conversionchar_code_to_str$( )str_to_char_code$( ) str_to_date$( )str_to_time$( )str_to_val$( )to_string$( )to_string_using$( )val_to_str$( )

TEXT Conversionstr_to_char_code$( ) str_to_date$( )str_to_time$( )str_to_val$( )substr$( )to_text$( )

BOOL Conversionto_bool$( )to_num$( )

DATE and TIME Conversiondate_to_mdy$( )mdy_to_date$( )null_convert$( )str_to_date$( )str_to_time$( )to_num$( )to_date$( )to_time$( )

NUMERIC Conversionto_amount$( )to_bool$( )to_num$( )

BINARY Conversionto_amount$( )to_binary$( )to_bool$( )to_num$( )





TypeConversion(continued)

FLOAT and AMOUNTConversionto_amount$( )to_float$( )to_num$( )

Null Value Conversionnull_convert$( )to_amount$( )to_date$( )to_float$( )to_num$( )

ACCELL/SQL ObjectConversionto_value$( )

StatusChecking

Check the status of theapplication, such as currentdate, state of current record,or the success of the lastdatabase operation.

aud_mode$( )check_dirty$( )current_record_count$( )current_record_num$( )dbms_status$( )dump_statistics$( )explicit_mode$( )is_current_record_ stored$( )l_wait_time$( )last_command$( )last_command_name$( )record_is_current$( ) show_dirty$( )sp_compute$( )sp_return$( )sp_select$( )sql_code$( )sql_errmsg$( )sql_status$( )status$( )tx_mode$( )





UserEnviron-ment

Obtain information about thesoftware environment of theuser, such as group ID orsystem values.

db_type$( )change_schema$( )current_date$( )current_time$( )get_default_schema$( )get_password$( )getenv$( )group_id$( )group_name$( )l_allow_interrupt$( )os_type$( )set_interrupt$( )ui_type$( )user_id$( )user_name$( )

Presentation Control presentation ofinterface options.

fyi_refresh_mode$( )set_button_color$( )set_field_color$( )

String orTextComparison

Compares a STRING or TEXTvariable with a special stringmask.

glob_str_compare$( )reg_exp_str_compare$( )


System Variables

You can use ACCELL/4GL system variables to test and change theinternal state of ACCELL/Manager. You can change variable values byusing the SET statement in the form script.

��

Category Description System Variable

DatabaseOperations

Change the internal state ofACCELL/Manager.

add_allowed$delete_allowed$find_allowed$update_allowed$

UserInformationLevel

Change the user informationlevel.

info_level$


Predefined C Functions

ACCELL/SQL provides predefined C functions for use as form scriptC-hook functions.

��

Category Description Function Name

C Function Perform operations outside ofACCELL/4GL.

uaclbw( )uaclcfld( )uacldbid( )uacldbp( )uaclform( )uacllda( )uaclrid( )uacltwid( )uacltx( )uaclwhr( )uaclwnd( )


ACCELL/4GL Form ScriptConventions

The ACCELL/4GL descriptions assume the following general conventionsabout ACCELL/4GL form scripts:

Event Sections

Event sections are optional in a form script, unless otherwise notedin the description.

You do not need to use the BEGIN and END keywords to surroundthe statements in an event section.

Statements

Statements must be placed within an event section, unlessotherwise noted in the description.

You can use either a single statement or a statement blockanywhere that statement appears in the syntax listings unlessotherwise noted in the description.

A statement_list is made up of one or more ACCELL/4GLstatements. A statement_block is also made up of one or morestatements. However, if the statement_block has more than onestatement, it must be introduced with the keyword BEGIN andconcluded with the keyword END.

A semicolon (;) is required to terminate an SQL statement.Semicolons are optional for terminating ACCELL/4GL statements.


System Functions and Variables

All system functions and variables have a dollar sign ($) as the lastcharacter. You must include the $ character when you use a systemfunction or system variable.

All system functions must include parentheses in the function call,regardless of whether the function has parameters.

When a system function returns a value, you can choose whetherto use this value in the form script.

System functions and system variables must be placed within anevent section.

Spaces between the system function parameters shown in theSyntax section are optional. Commas between parameters arerequired.

An entire array variable cannot be passed to ACCELL/SQL systemfunctions or to C-hook functions directly. However, the values ofindividual elements of an array can be passed to a function.

Punctuation

When you write form scripts, use the following punctuation to specifystring values, variable names, and keywords.

Delimit a string value, including the string value of an attribute, byapostrophes, as in ’string’, for example:

SET course_code:CASE_CONVERSION TO ’UPPER’

Delimit a variable name by double quotation marks, as in”variable_name”, if the variable name is the same as anACCELL/SQL keyword or the name of a user-defined variable, forexample:

”Company_address”

Prefix an ACCELL/SQL variable by a dollar sign, as in$variable_name, when the variable appears in an SQL statementbut is not prefixed by a form name, for example:

$emp_number

39

Attributes Summary

40 Attributes Summary

��

This chapter summarizes all ACCELL/SQL attributes. Attributes are listedin alphabetical order. The summary table for each attribute indicateswhether the attribute is settable in ACCELL/Generator and inACCELL/4GL form scripts. Valid values lists possible values; a valueshown in boldface type is the default setting.

For information about how to set attributes in ACCELL/Generator, see�� . For information about howattributes affect runtime operation of an application, see �� . For information about how to set an attribute in anACCELL/4GL form script, see the description of the SET statement givenin the “ACCELL/4GL Syntax Descriptions” chapter of this manual.

41Attributes Summary

The ACCELL_TYPE attribute provides the data type of a variable.

For a general variable, this attribute is automatically initialized with thedata type of the first value you assign to the general variable.

For a field variable, this attribute is initialized with the field data typeyou specified in ACCELL/Generator.

For a target variable, this attribute is initialized with the ACCELL/SQLdata type that corresponds to the database column data type.

ACCELL_TYPE General Attribute

ACCELL/Generator Form: Field DefinitionField: Data Type

ACCELL/4GL Read-only

Data type String

Valid values AMOUNTBINARYBOOLDATE

FLOATNUMERICROWID

STRINGTEXTTIME

DATA_TYPE

��

The ACTION attribute sets the command action in both find mode andadd/update/delete mode.

ACTION Command Key Attribute

ACCELL/Generator Not settable

ACCELL/4GL Settable

Data type Action specifier

Valid values ENABLEDDISABLED

��

��

DEFINE COMMAND, SET COMMAND in this manual“Defining User Commands” in ��

ACCELL_TYPE

Summary

Related Attributes

See Also

ACTION

Summary

Related Attributes

See Also


When the ADD_ALLOWED attribute is set to TRUE, the user haspermission to perform interactive add operations. ACCELL/Managernotifies the user if an attempt is made to perform an operation for whichthe user does not have form access privilege.

ADD_ALLOWED Form Attribute

ACCELL/Generator Form: Form DefinitionField: Insert Allowed

ACCELL/4GL Settable

Data type Boolean

Valid values TRUEFALSE

��

��

��

SET, add_allowed$ in this manual“Creating Screen Forms” in �� AMGR in �� ! ��"� ��#$��%�&��$��'��

The AUD_ACTION attribute specifies the command action foradd/update/delete mode. This attribute has no effect in find mode.

AUD_ACTION Command Key Attribute


ACCELL/4GL Settable


Valid values DISABLEDENABLED

��

��


ADD_ALLOWED

Summary

Related Attributes

See Also

AUD_ACTION

Summary

Related Attributes

See Also


The AUD_LABEL attribute specifies the command prompt foradd/update/delete mode. This attribute has no effect in find mode.

AUD_LABEL Command Key Attribute


ACCELL/4GL Settable

Data type String

Valid values Any string

��

��


The AUD_ON_ENTRY attribute determines whether the form isinitialized to add/update/delete mode upon entry to the form.

When the AUD_ON_ENTRY attribute is set to TRUE, ACCELL/Managerperforms a clear-to-add operation and form execution begins inadd/update/delete mode. If the AUD_ON_ENTRY attributes is FALSE,ACCELL/Manager initializes the form to find mode.

AUD_ON_ENTRY Form Attribute

ACCELL/Generator Form: Form DefinitionField: Aud On Entry

ACCELL/4GL SettableACCELL/Manager checks the AUD_ON_ENTRY formattribute only after completing execution of theBEFORE FORM section. Set this attribute in theBEFORE FORM section if you need for it to takeeffect when form execution begins.

Data type Boolean

Valid values TRUEFALSEDefault: FALSE for a form that has a target table;TRUE for a form that has no target table.

AUD_LABEL

Summary

Related Attributes

See Also

AUD_ON_ENTRY

Summary


AUTO_FIND

“Creating Screen Forms” in �� “Add/Update/Delete Mode” in ��

When the AUTO_ACCEPT attribute is set to TRUE, ACCELL/Managerautomatically proceeds to the next field when the user has entered datainto the entire length of the field. This attribute is FALSE for all TEXTvariables.

This attribute has no effect in either find mode or graphical presentationmodes.

AUTO_ACCEPT Field Attribute

ACCELL/Generator Form: Field DefinitionField: Auto Accept

ACCELL/4GL Settable

Data type Boolean


FIELD_LENGTH

“Creating Screen Form Fields” in �� (� ��#�$��'�)!�%�$��

Related Attributes

See Also

AUTO_ACCEPT

Summary

Related Attributes

See Also


When the AUTO_COMMIT attribute is set to TRUE, ACCELL/Managerperforms a Transaction Commit after a successful interactive databaseoperation (add, update, or delete).

If this attribute is set to FALSE, interactive database operations are notcommitted automatically.

AUTO_COMMIT Form Attribute

ACCELL/Generator Form: Form DefinitionField: Auto Commit

ACCELL/4GL Settable

Data type Boolean


“Creating Screen Forms” in �� “Controlling ACCELL/SQL Transactions” in ��

The AUTO_EDIT attribute determines whether text edit mode isautomatically enabled when the cursor stops on a text field. When set toTRUE, text edit mode is turned on when the cursor stops on the text field.If the UPDATEABLE attribute is set to FALSE, the user is allowed only toscroll through the text field; other editing commands have no effect.

This attribute has no effect in graphical presentation modes.

AUTO_EDIT Field Attribute

ACCELL/Generator Form: Field DefinitionField: Auto Edit

ACCELL/4GL Settable

Data type Boolean


UPDATEABLE


AUTO_COMMIT

Summary

See Also

AUTO_EDIT

Summary

Related Attributes

See Also


When the AUTO_FIND attribute is set to TRUE, ACCELL/Managerperforms an implicit find operation after executing the BEFORE FORMsection. Search conditions for the find operation can be specified by theCLEAR_FIND_EXP and SEARCH_RANGES attributes.

If the AUD_ON_ENTRY attribute is FALSE and the AUTO_FIND attributeis TRUE, ACCELL/Manager initiates a clear-to-find operation followed bya find operation. If both the AUTO_FIND and AUD_ON_ENTRYattributes are FALSE, ACCELL/Manager initializes the form to find mode.

This attribute has no effect when the AUD_ON_ENTRY attribute is set toTRUE.

AUTO_FIND Form Attribute

ACCELL/Generator Form: Form DefinitionField: Auto Find

ACCELL/4GL Settable: standard form scripts onlyWhen the AUTO_FIND attribute is set to TRUE, thefollowing event sections are executed after theBEFORE FORM section:

ON CLEAR TO FINDBEFORE FINDON FINDAFTER FIND

To initialize a form to find mode, set this attribute inthe BEFORE FORM section. To set search criteria forthe find operation, include the clear-to-find andSearch Ranges expressions in either the BEFOREFORM or BEFORE FIND sections.

Data type Boolean


��

��

��

“Creating Screen Forms” in �� “Find Mode” in ��

AUTO_FIND

Summary

Related Attributes

See Also


When the AUTO_ZOOM attribute is set to TRUE, ACCELL/Managerautomatically activates the zoom form if a zoom form has been enabledfor the field.

AUTO_ZOOM Field Attribute

ACCELL/Generator Form: Field DefinitionField: Auto Zoom

ACCELL/4GL Settable

Data type Boolean


ENABLE ZOOM in this manual“Creating Screen Form Fields” in ��

When the BLINK attribute is set to TRUE, the field display is set forblinking video.


BLINK Field Attribute

ACCELL/Generator Form: Field DefinitionField: Field Video Attributes: Blink

ACCELL/4GL Settable

Data type Boolean


��

��!��

��


AUTO_ZOOM

Summary

See Also

BLINK

Summary

Related Attributes

See Also


The BOUNDED attribute indicates whether an array is bounded orunbounded. For general variables, array bounds are defined by theLOCAL clause in the FORM section or FUNCTION statement. All arraysdefined on a screen form are bounded.

BOUNDED Array Variable Attribute

ACCELL/Generator Form: Array Definition(s) form


Data type Boolean

Valid values TRUEFALSEDefault: TRUE unless UNKNOWN keyword isspecified in the LOCAL clause

��"��

��"��

��

��

��

��

FORM, FUNCTION in this manual“Creating Screen Form Fields” in �� “Using ACCELL/4GL Components” and “Controlling InformationDisplay” in ��

BOUNDED

Summary

Related Attributes

See Also


The CASE_CONVERSION attribute determines the type of caseconversion to be performed for a STRING or TEXT field.

This attribute has a different effect in graphical presentation modes.

CASE_CONVERSION Field Attribute

ACCELL/Generator Form: Field DefinitionField: Case Conversion

ACCELL/4GL Settable

Data type String

Valid values NONEUPPERLOWER

“Creating Screen Form Fields” in �� *�$��$�� ) ��+��$�&�� (� ��#�$��'�)!�%�$��

CASE_CONVERSION

Summary

See Also


The CLEAR_ADD_EXP attribute contains an ACCELL/SQL expressionthat is evaluated when a clear-to-add operation occurs. The result is thenassigned to the variable.

The CLEAR_ADD_EXP attribute cannot be initialized by a SELECTstatement.

This attribute has no effect in find mode.

CLEAR_ADD_EXP General Attribute


ACCELL/4GL SettableThis attribute is not readable.The CLEAR_ADD_EXP expression is evaluatedbefore the ON CLEAR TO ADD section is executed.A Clear To Add expression that is set in the ONCLEAR TO ADD section will not be evaluated untilthe next Clear To Add operation occurs.

Data type The value yielded by the expression must be of thesame type as the associated variable.

Valid values A constant value, or an ACCELL/SQL expressionenclosed within a pair of apostrophes (’).Default: UNDEFINED

��

��

SET“Add/Update/Delete Mode” in ��

When the CLEAR_AFTER_AU attribute is set to TRUE,ACCELL/Manager performs an implicit Clear To Add operation after anew row is added interactively. A Clear To Add operation is notperformed when an existing row is updated.

When this attribute is set to TRUE, the form can accept continuous dataentry in add/update/delete mode. Each time a selected set record is added,the form is automatically cleared to accept another record.

If this attribute is set to FALSE, the user must press �� tostart a new entry.

This attribute does not initialize the form to add/update/delete mode.

CLEAR_ADD_EXP

Summary

Related Attributes

See Also

CLEAR_AFTER_AU


CLEAR_AFTER_AU Form Attribute

ACCELL/Generator Form: Form DefinitionField: Clear After Add

ACCELL/4GL SettableThe ON CLEAR TO ADD section is executedwhenever a Clear To Add operation occurs.

Data type Boolean


CLEAR_ADD_EXP

“Creating Screen Forms” in �� “Add/Update/Delete Mode” in ��

The CLEAR_FIND_EXP attribute is an expression that sets the initialsearch criteria for target table fields when a clear-to-find operation isexecuted. The clear-to-find expression is evaluated, and the resultingvalue is assigned to the SEARCH_RANGES attribute. The initial searchcriteria are displayed on the form and can be modified by the user.

A clear-to-find expression can be any of the following:

a constant value (including NULL)

an expression

a range of values or a value limit that uses the => operator

a string containing pattern-matching metacharacters

The CLEAR_FIND_EXP attribute cannot be initialized by a SELECTstatement.

This attribute has no effect in add/update/delete mode.

Summary

Related Attributes

See Also

CLEAR_FIND_EXP


CLEAR_FIND_EXP Target Variable Attribute


ACCELL/4GL Settable: standard form scripts only

Data type String expression

Valid values The value yielded by the expression must be of thesame type as the associated variable.Default: UNDEFINED

��

��

��

�#��"��

NEXT ACTION, ON CLEAR TO FIND, SET in this manual“Find Mode” in ��

For graphical user interfaces only. Specifies whether the user canmove from field to field by moving the pointer and clicking a mousebutton. This attribute is enabled only when the clickOnField applicationresource specifies a mouse button. This attribute has no effect incharacter mode applications.

CLICK_ON_FIELD Form Attribute

ACCELL/Generator Form: Form DefinitionField: Click on Field


Data type Boolean


��*�$��$�� ) ��+��$�&��

Summary

Related Attributes

See Also

CLICK_ON_FIELD

Summary

See Also


The COL attribute specifies the column position of a field relative to theform (not the screen). An error occurs if you attempt to place a columnoutside the area of the form.

COL Field Attribute

ACCELL/Generator Settable with the field-positioning commands

ACCELL/4GL Settable

Data type Numeric

Valid values An integer value greater than or equal to 0, up to themaximum available on the form.

ROW

“Creating Screen Form Fields” in ��

The COL_ORIGIN attribute specifies the column number of the upperleft corner of the screen form.

COL_ORIGIN Form Attribute

ACCELL/Generator Settable with the form-positioning commands


Data type Numeric

Valid values Integer greater than or equal to 0, up to the maximumavailable on the screenDefault: row 1, column 0

ROW_ORIGIN

“Positioning a Form” in ��

The COLUMN_INDEX attribute provides the value of the columnsubscript of a two-dimensional (MATRIX) array cell reference. Forexample, the value of mat[1,7]:COLUMN_INDEX is 7.

Within a FIELD section, an array self-reference can be used to specifythe current column subscript of the current form field array cell, forexample:

FIELD MATRIX matSWITCH(mat[]:COLUMN_INDEX)

COL

Summary

Related Attributes

See Also

COL_ORIGIN

Summary

Related Attributes

See Also

COLUMN_INDEX


COLUMN_INDEX Array Variable Attribute

ACCELL/Generator Form: Field DefinitionField: Dimension


Data type Numeric

Valid values Any numeric value

��

��

“Creating Screen Form Fields” in �� ,“Using ACCELL/4GL Components” and “Controlling InformationDisplay” in ��

The COLUMN_LOWER_BOUNDS attribute provides the value of thelower bounds of a column in a two-dimensional (MATRIX) array.

COLUMN_LOWER_BOUNDS Array Variable Attribute

ACCELL/Generator Form: Array Definition(s)Field: 2nd Dim. Bounds: Lower

ACCELL/4GL Read-onlyUse to test the array column lower bounds.

Data type Numeric

Valid values Any numeric valueDefault (ACCELL/Generator): 1

��

��"��

��

��

��

��


Summary

Related Attributes

See Also

COLUMN_LOWER_BOUNDS

Summary

Related Attributes

See Also


The COLUMN_UPPER_BOUNDS attribute provides the value of theupper bounds of a column in a two-dimensional (MATRIX) array.

COLUMN_UPPER_BOUNDS Array Variable Attribute

ACCELL/Generator Form: Array Definition(s)Field: 2nd Dim. Bounds: Upper

ACCELL/4GL Read-onlyUse to test the array column upper bounds.

Data type Numeric


��

��"��

��

��

��

��

FORM, FUNCTION, “Creating Screen Form Fields” in �� , “Using ACCELL/4GL Components” and“Controlling Information Display” in ��

The CUR_FIELD attribute specifies the name of the current field.

CUR_FIELD Form Attribute



Data type String

Valid values The name of a form field

��

��

��

��!��

“Controlling Form Events” in ��

COLUMN_UPPER_BOUNDS

Summary

Related Attributes

See Also

CUR_FIELD

Summary

Related Attributes

See Also


The CUR_NEXT_FIELD attribute determines the field to be executedwhen the user presses �� .

CUR_NEXT_FIELD Form Attribute


ACCELL/4GL SettableAn assignment to CUR_NEXT_FIELD is temporaryand remains in effect only until ACCELL/Managermoves to the next field. CUR_NEXT_FIELD is thenreset with the new current field’s NEXT_FIELD fieldattribute.

Data type String


��

��

��

��!��


CUR_NEXT_FIELD

Summary

Related Attributes

See Also


The DATA_TYPE attribute provides the ACCELL/SQL data type of thefield or variable.

For a general variable, this attribute is automatically initialized with thedata type of the first value you assign to the general variable.

For a field variable, this attribute is initialized with the form field datatype you specified in ACCELL/Generator.

For a target variable, this attribute is initialized with the defaultACCELL/SQL data type to which the database column data type isconverted.

DATA_TYPE Field Attribute

ACCELL/Generator Form: Field DefinitionField: Data Type


Data type String


FLOATNUMERICROWID

STRINGTEXTTIME

ACCELL_TYPE


The DB_LENGTH attribute specifies the length of the database columnassociated with the target field. The length of a TEXT variable field is setto 0.

DB_LENGTH Target Variable Attribute



Data type Numeric

Valid values Default: The length of the associated databasecolumn

DATA_TYPE

Summary

Related Attributes

See Also

DB_LENGTH

Summary


The DB_TYPE attribute specifies the ACCELL/SQL data type keywordthat indicates the data type of the database column that is associated withthe target field.

DB_TYPE Target Variable Attribute



Data type String


DATE_TIMEFLOATNUMERICROWID

STRINGTEXTTIME

�� : “Using RDBMS Data Types WithACCELL/SQL Applications”

When the DELETE_ALLOWED attribute is set to TRUE, the user haspermission to perform interactive delete operations. ACCELL/Managernotifies the user if an attempt is made to perform an operation for whichthe user does not have form access privilege.

DELETE_ALLOWED Form Attribute

ACCELL/Generator Form: Form DefinitionField: Delete Allowed

ACCELL/4GL Settable

Data type Boolean


��

��

��

SET, delete_allowed$ in this manual“Creating Screen Forms” in �� AMGR in �� ! ��"� ��#$��%�&��$��'��

DB_TYPE

Summary

See Also

DELETE_ALLOWED

Summary

Related Attributes

See Also


The DIMENSION attribute provides the number of dimensions of anarray.

DIMENSION Array Variable Attribute

ACCELL/Generator Form: Array Definition(s)Field: Dimension


Data type Numeric

Valid values 012

“Creating Screen Form Fields” in �� “Array Variables” in the “Variables” chapter of �� *��#!�� *�$�� ,��

The DISPLAY_FORMAT attribute specifies the display format for thefield. The format consists of a format template that defines how the datais to be formatted. This variable is not used for TEXT variables.

DISPLAY_FORMAT Field Attribute

ACCELL/Generator Form: Field DefinitionField: Display Format

ACCELL/4GL Settable

Data type String

Valid values Default: zero-length string

DISPLAY in this manual“Creating Screen Form Fields” in ��

DIMENSION

Summary

See Also

DISPLAY_FORMAT

Summary

See Also


The DISPLAY_JUSTIFY attribute determines the type of justification forfield data.

DISPLAY_JUSTIFY Field Attribute

ACCELL/Generator Form: Field DefinitionField: Display Justify

ACCELL/4GL Settable

Data type String

Valid values LEFTCENTEREDRIGHT


When the ECHOED attribute is set to FALSE, the field does not displaydata on the screen. Use this attribute to prevent the display of confidentialinformation, such as a password.

ECHOED Field Attribute

ACCELL/Generator Form: Field DefinitionField: Echo

ACCELL/4GL Settable

Data type Boolean



DISPLAY_JUSTIFY

Summary

See Also

ECHOED

Summary

See Also


The ESTIMATED_COUNT attribute provides the value of the estimatednumber of rows identified for an unbounded array. The estimated numberof rows is specified by the ESTIMATING keyword of the LOCAL clausein the FORM section or FUNCTION statement; if not specified, theestimated number of rows is 100.

Use this attribute to test whether memory is used efficiently. If the upperbounds increases significantly beyond the estimated count, memory canbecome fragmented.

ESTIMATED_COUNT Array Variable Attribute



Data type Numeric

Valid values Any numeric valueDefault: 100

FORM, FUNCTION in this manual

For information about how to display the value of a variable at runtime,see �� *��#!�� *�$�� ,�� .

In add/update/delete mode, the FIELD_LENGTH attribute provides theinput length (the maximum number of characters that can be entered).Input length cannot be specified for a TEXT variable.

This attribute has no effect in find mode.

FIELD_LENGTH Field Attribute

ACCELL/Generator Form: Field DefinitionField: Field Length

ACCELL/4GL Settable

Data type Numeric

Valid values Integer greater than or equal to 0. For database fields,the default is the input length of the data type of thedatabase column. For nondatabase fields, the defaultlength is set by the Session Defaults form.

AUTO_ACCEPT

ESTIMATED_COUNT

Summary

See Also

FIELD_LENGTH

Summary

Related Attributes



The FIELD_NAME attribute provides the form field name.

FIELD_NAME Field Attribute

ACCELL/Generator Form: Field DefinitionField: Field Name


Data type String



The FILE_PATH attribute specifies the full path name of a file thatcontains a text or binary value. This attribute is undefined when theIN_MEMORY attribute is TRUE. The default path is determined by thesettings of configuration variables (listed below).

FILE_PATH General Attribute



Data type String

Valid format For text: /usr/tmp/atxtpidindxFor binary: /usr/tmp/abinpidindx

IN_MEMORY

ACLVARDIR, ACLVARMEMLIM, AGEN_SEL_SET_DR, AMGR_SEL_SET_DRin �� ! ��"� ��#$��%�&��$��'��

See Also

FIELD_NAME

Summary

See Also

FILE_PATH

Summary

Related Attributes

See Also


The FIND_ACTION attribute specifies the function key action in findmode. This attribute has no effect in add/update/delete mode.

FIND_ACTION Command Key Attribute


ACCELL/4GL Settable


Valid values ENABLED DISABLED

��

��


When the FIND_ALLOWED attribute is set to TRUE, the user haspermission to perform interactive find operations on the form’s targettable. The form must have a target table.

ACCELL/Manager notifies the user if an attempt is made to perform anoperation for which the user does not have form access privilege.

FIND_ALLOWED Form Attribute

ACCELL/Generator Form: Form DefinitionField: Find Allowed


Data type Boolean


��

��

��

FIND_ACTION

Summary

Related Attributes

See Also

FIND_ALLOWED

Summary

Related Attributes


SET, find_allowed$“Creating Screen Forms” in �� AMGR in �� ! ��"� ��#$��%�&��$��'��

The FIND_COUNT attribute specifies the maximum number of records tobe placed in the selected set before returning control to the user. Thisattribute sets the browse feature of find mode. Using the browse feature,ACCELL/Manager adds only a specified number of records to the selectedset at one time. After it adds each subset of records to the selected set,ACCELL/Manager suspends the target table search. The search is resumedwhen the user moves to the end of the current selected set. This processoccurs each time the user passes the selected set’s end boundary until nomore records satisfy the search criteria.

A setting of 0 specifies that all matching records are placed in theselected set.


FIND_COUNT Form Attribute

ACCELL/Generator Form: Form DefinitionField: Find Count


Data type Numeric

Valid values A positive integer up to the maximum allowed byyour operating systemDefault: 0 (All records are placed in the selected set.)


See Also

FIND_COUNT

Summary

See Also


The FIND_LABEL attribute specifies the command prompt for findmode. This attribute has no effect in add/update/delete mode.

FIND_LABEL Command Key Attribute


ACCELL/4GL Settable

Data type String

Valid values Any stringDefault: zero-length empty string

��

��


When the FINDABLE attribute determines whether a field accepts searchcriteria from the user in find mode.

When FINDABLE is set to FALSE, the user cannot enter search criteriawhen the form is in find mode; however the user can modify the data inthe field when the form is in add/update/delete mode. In find mode,execution pauses at the field if STOP_FOR_INPUT is TRUE, but the usercannot modify the field.

This attribute has no effect when STOP_FOR_INPUT is set to FALSE.

FINDABLE Field Attribute

ACCELL/Generator Form: Field DefinitionField: Findable

ACCELL/4GL Settable

Data type Boolean


��

��


FIND_LABEL

Summary

Related Attributes

See Also

FINDABLE

Summary

Related Attributes

See Also


The FIRST_FIELD attribute specifies the name of the first field to beexecuted on the form. If STOP_FOR_INPUT is set to FALSE,ACCELL/Manager continues moving to the next field until it encounters aform field where STOP_FOR_INPUT is set to TRUE.

If no form fields have STOP_FOR_INPUT set to TRUE, the form isdisplayed momentarily, followed by the next form.

In add/update/delete mode, ACCELL/Manager stops only on form fieldswhere STOP_FOR_INPUT is set to TRUE.

FIRST_FIELD Form Attribute

ACCELL/Generator Form: Form DefinitionField: First Field

ACCELL/4GL SettableAll FIELD sections are executed for the first fieldwhere STOP_FOR_INPUT is set to TRUE.

Data type String

Valid values The name of a form fieldDefault: The name of the field closest to the upperleft corner of the form.

��

��

��

��

“Creating Screen Forms” in �� “Controlling Form Events” in ��

FIRST_FIELD

Summary

Related Attributes

See Also


The FORM_NAME attribute specifies the name of the current form.

FORM_NAME Form Attribute

ACCELL/Generator Form: Form DefinitionField: Form Name


Data type String

Valid values Any string of up to 15 charactersDefault: None

PREV_FORM

“Creating Screen Forms” in ��

The FYI_MESSAGE attribute specifies the information messagedisplayed in the fyi_message system information field. If the screenformat does not include this field, the message cannot be displayed.

FYI_MESSAGE Field Attribute

ACCELL/Generator Form: Field DefinitionField: FYI Message

ACCELL/4GL Settable

Data type String

Valid values Any string, up to 78 characters

DISPLAY in this manual“Creating Screen Form Fields” in ��

FORM_NAME

Summary

Related Attributes

See Also

FYI_MESSAGE

Summary

See Also


The HEIGHT attribute specifies the number rows of the screen form asdrawn in ACCELL/Generator. This number remains constant, regardlessof whether the form is expanded at runtime for a repeating area.

HEIGHT Form Attribute

ACCELL/Generator Settable with the �� command


Data type Numeric

Valid values An integer greater than or equal to 0Default: By default new forms have 15 rows.

��

��


The HELP_ARCHIVE attribute specifies the path name of the helparchive file for the form or field.

HELP_ARCHIVE Field Attribute

ACCELL/Generator Form: Form DefinitionField: Help Archive

ACCELL/4GL Settable

Data type String

Valid values Any string of up to 255 characters; can include a fulldirectory path specification. The name of the file isautomatically generated based upon the form nameand has a suffix of .hlp. You can change the name.Default: field_name.hlp


HEIGHT

Summary

Related Attributes

See Also

HELP_ARCHIVE

Summary

See Also


The HELP_FORM_COL attribute specifies the column position of thehelp form for the field.

HELP_FORM_COL Field Attribute


ACCELL/4GL Settable

Data type Numeric

Valid values Integer greater than or equal to 0, up to the maximumnumber of columns available on the screen

HELP_FORM_ROW


The HELP_FORM_NAME attribute specifies the name of the help formfor the field.

HELP_FORM_NAME Field Attribute

ACCELL/Generator Form: Field DefinitionField: Help Form Name

ACCELL/4GL Settable

Data type String

Valid values Any string of up to 15 characters. The name of thefile is automatically generated based upon the formname and has a suffix of _hlp. You can change thename.Default: field_name_hlp


HELP_FORM_COL

Summary

Related Attributes

See Also

HELP_FORM_NAME

Summary

See Also


The HELP_FORM_ROW attribute specifies the row position of the helpform for the field.

HELP_FORM_ROW Field Attribute


ACCELL/4GL Settable

Data type Numeric

Valid values An integer greater than or equal to 0, up to themaximum number of rows available on the screen

HELP_FORM_COL


The IN_MEMORY attribute indicates whether a variable is in memory.For variable types other than TEXT or BINARY, this attribute is alwaysTRUE. For TEXT or BINARY variables, this attribute can be either TRUEor FALSE. When IN_MEMORY is FALSE, the FILE_PATH attributecontains a string that identifies the full path name of the text or binaryfile.

IN_MEMORY General Attribute



Data type Boolean


FILE_PATH

ACLVARMEMLIM in �� ! ��"� ��#$��%�&��$��'��

HELP_FORM_ROW

Summary

Related Attributes

See Also

IN_MEMORY

Summary

Related Attributes

See Also


The LABEL attribute sets the command key prompt in both find modeand add/update/delete mode.

LABEL Command Key Attribute


ACCELL/4GL Settable

Data type String

Valid values Any stringDefault: zero-length empty string

��

��


The LIST_INDEX attribute provides the value of the row subscript of aone-dimensional (LIST) array cell reference. For example, the value ofalist[1]:LIST_INDEX is 1.

Within a FIELD section, an array self-reference can be used to specifythe current row subscript of the current form field array cell, for example:

FIELD LIST studentSWITCH(student[]:LIST_INDEX)

LIST_INDEX Array Variable Attribute



Data type Numeric


��"��

��

FORM, “Creating Screen Form Fields” in �� . “Using ACCELL/4GL Components” and “ControllingInformation Display” in ��

LABEL

Summary

Related Attributes

See Also

LIST_INDEX

Summary

Related Attributes

See Also


The LIST_LOWER_BOUNDS attribute provides the value of the lowerbounds of a one-dimensional (LIST) array.

LIST_LOWER_BOUNDS Array Variable Attribute

ACCELL/Generator Form: Array Definition(s)Field: 1st Dim. Bounds: Lower

ACCELL/4GL Read-onlyUse to test the array list lower bounds.

Data type Numeric


��

��"��

��"��

��

��

��


The LIST_UPPER_BOUNDS attribute provides the value of the upperbounds of a one-dimensional (LIST) array.

LIST_UPPER_BOUNDS Array Variable Attribute

ACCELL/Generator Form: Array Definition(s)Field: 1st Dim. Bounds: Upper

ACCELL/4GL Read-onlyUse to test the array list upper bounds.

Data type Numeric


��

��"��

��"��

��

��

��

LIST_LOWER_BOUNDS

Summary

Related Attributes

See Also

LIST_UPPER_BOUNDS

Summary

Related Attributes



When the LOW_INTENSITY attribute is set to TRUE, the field display isset for low intensity video.


LOW_INTENSITY Field Attribute

ACCELL/Generator Form: Field DefinitionField: Field Video Attributes: Low Intensity

ACCELL/4GL Settable

Data type Boolean


��$

��!��

��

“Creating Screen Form Fields” in �� (� ��#�$��'�)!�%�$�� *�$��$�� ) ��+��$�&��

See Also

LOW_INTENSITY

Summary

Related Attributes

See Also


The MENU_LABEL attribute specifies the menu label to be displayed ona Next Form menu where a choice of more than one form is possible fora next form.

MENU_LABEL Form Attribute

ACCELL/Generator Form: Form DefinitionField: Menu Label


Data type String

Valid values Up to 70 characters for a single-column format; nomore than 35 characters for a two-column format.Default: The names of the next forms


The MULTI_VALUED attribute specifies whether the field has a separate,distinct value for each record in the selected set.

MULTI_VALUED Field Attribute

ACCELL/Generator Form: Field DefinitionField: Multi Valued


Data type Boolean

Valid values TRUEFALSEDefault: TRUE for database fields


MENU_LABEL

Summary

See Also

MULTI_VALUED

Summary

See Also


The NEXT_FIELD attribute specifies the name of the next field for afield. These attributes are initialized in ACCELL/Generator according tothe order the fields are defined in the form and whether the form usesrow or column field order. The NEXT_FIELD attribute value can bechanged in any script section; however, the setting has no effect in thecurrent field. The next field for the current field is determined by theCUR_NEXT_FIELD attribute. Changing the NEXT_FIELD attribute takeseffect the next time the field is made current.

NEXT_FIELD Field Attribute

ACCELL/Generator Form: Form DefinitionField: Field Order

ACCELL/4GL SettableUse this attribute in the form script to change thefield order chain.

Data type String


��

��

��

��!��


The OCCURRENCES attribute specifies the number of occurrences ofthe repeating area of the form.

OCCURRENCES Form Attribute

ACCELL/Generator Form: Form DefinitionField: Occurrences


Data type Numeric

Valid values An integer greater than or equal to 0, up themaximum the screen will allow.

HEIGHTWIDTH


NEXT_FIELD

Summary

Related Attributes

See Also

OCCURRENCES

Summary

Related Attributes

See Also


The PREV_FIELD attribute specifies the name of the previous Stop ForInput field.

PREV_FIELD Form Attribute



Data type String

Valid values The name of a field on the current formDefault: Field order is determined by the setting ofthe Field Order field of the Form Definition form

��

��

��

“Controlling Form Events” in �� *�$��$�� ) ��+��$�&��

The PREV_FORM attribute specifies the name of a form’s previous form.

PREV_FORM Form Attribute



Data type String

Valid values A form nameDefault: The name of the previous form at runtime

FORM_NAME

When the REQUIRED attribute is set to TRUE, the user must enter data inthe field when the cursor arrives at this field. The user cannot move ontothe next field without entering input. A database add operation failsunless the user has entered a value in all form fields that haveREQUIRED set to TRUE. If the user does not supply a valid value foreach required field on the form, the add operation is not allowed.

This attributes has no effect when STOP_FOR_INPUT is set to FALSE.

PREV_FIELD

Summary

Related Attributes

See Also

PREV_FORM

Summary

Related Attributes

REQUIRED


REQUIRED Field Attribute

ACCELL/Generator Form: Field DefinitionField: Required

ACCELL/4GL Settable

Data type Boolean


STOP_FOR_INPUT


The RETRIEVE_VALUE attribute specifies whether a target table columnis retrieved by the application. Except for binary fields, by defaultACCELL/SQL retrieves all target table columns when a find operation isexecuted.

To improve application performance, set this attribute to FALSE for atarget table column that is not required by the application. When rows areselected from the target table for the form, only those columns areretrieved where RETRIEVE_VALUE is set to TRUE for the targetvariable. The default value for binary fields is FALSE. IfRETRIEVE_VALUE is set to TRUE for a text or binary field, the entirevalue of the database column is retrieved.

RETRIEVE_VALUE Target Variable Attribute

ACCELL/Generator Form: Field DefinitionField: Retrieve Value

ACCELL/4GL Settable

Data type Boolean

Valid values TRUEFALSEFor nontarget or binary fields, the default is FALSE.For target fields, the default is TRUE.


Summary

Related Attributes

See Also

RETRIEVE_VALUE

Summary

See Also


When the REVERSE attribute is set to TRUE, the field display is set forreverse video.


REVERSE Field Attribute

ACCELL/Generator Form: Field DefinitionField: Field Video Attributes: Reverse

ACCELL/4GL Settable

Data type Boolean


��$

��

��

“Creating Screen Form Fields” in �� *�$��$�� ) ��+��$�&��

The ROW attribute specifies the column position of the field relative tothe form (not the screen). An error occurs if you attempt to place acolumn outside the area of the form.

ROW Field Attribute

ACCELL/Generator Settable with the field-positioning commands

ACCELL/4GL Settable

Data type Numeric

Valid values An integer greater than or equal to 0, up to themaximum available on the form

COL


REVERSE

Summary

Related Attributes

See Also

ROW

Summary

Related Attributes

See Also


The ROW_INDEX attribute provides the value of row subscript of atwo-dimensional (MATRIX) array cell reference. For example, the valueof mat[1,7]:ROW_INDEX is 1.

Within a FIELD section, an array self-reference can be used to specifythe current row subscript of the current form field array cell, for example:

FIELD MATRIX matSWITCH(mat[]:ROW_INDEX)

ROW_INDEX Array Variable Attribute



Data type Numeric


��"��

��

“Creating Screen Form Fields” in �� “Using ACCELL/4GL Components” and “Controlling InformationDisplay” in ��

The ROW_LOWER_BOUNDS attribute provides the value of the lowerbounds of a row in a two-dimensional (MATRIX) array.

ROW_LOWER_BOUNDS Array Variable Attribute

ACCELL/Generator Form: Array Definition(s)Field: 1st Dim. Bounds: Lower

ACCELL/4GL Read-onlyUse to test the array column upper bounds.

Data type Numeric


��

��"��

��"��

��

��

��

ROW_INDEX

Summary

Related Attributes

See Also

ROW_LOWER_BOUNDS

Summary

Related Attributes



The ROW_ORIGIN attribute specifies the row number of the upper leftcorner of the screen form.

ROW_ORIGIN Form Attribute



Data type Numeric

Valid values Integer greater than or equal to 0Default: 1

COL_ORIGIN


The ROW_UPPER_BOUNDS attribute provides the value of the upperbounds of a row in a two-dimensional (MATRIX) array.

ROW_UPPER_BOUNDS Array Variable Attribute

ACCELL/Generator Form: Array Definition(s)Field: 1st Dim. Bounds: Upper

ACCELL/4GL Read-onlyUse to text the array column upper bounds.

Data type Numeric


��

��"��

��"��

��

��

��

See Also

ROW_ORIGIN

Summary

Related Attributes

See Also

ROW_UPPER_BOUNDS

Summary

Related Attributes



The SEARCH_RANGES attribute contains search criteria for a targetvariable or target field variable.

When a clear-to-find operation is initiated, ACCELL/Manager evaluatesthe clear-to-find expressions for the form and assigns the resulting valuesto the SEARCH_RANGES attributes for each variable. TheSEARCH_RANGES attribute can be changed in response to user input orby form script assignment statements to SEARCH_RANGES.

You can clear the SEARCH_RANGES value by assigning a zero-lengthstring to it, for example:

SET total:SEARCH_RANGES TO ’’;

If a variable does not have a CLEAR_FIND_EXP attribute set,ACCELL/Manager sets its SEARCH_RANGES attribute to a zero-lengthstring.

The following table lists the possible forms of clear-to-find expressionsand examples of the initial SEARCH_RANGES values displayed to theuser.

Clear-To-FindExpression Example*

Search RangesSetting

expr1, expr2 1, $var1, $var1 + $var2

’abc*’, ’def*’

1, 2, 5

abc*, def*

expr current_date$( )

user_name$( )

04/22/91

Moszkowski

=> expr => 10

=> ’aaa’

<10

<aaa

See Also

SEARCH_RANGES


Clear-To-FindExpression

Search RangesSettingExample*

expr => 10 =>

’aaa’ = >

>10

>aaa

expr1 => expr2 1 => $var2

’a*’ => ‘b*’

1–3

a*–b*

null_exprNULL NULL @

* where $var1=1 and $var2=3.

SEARCH_RANGES Target Variable Attribute


ACCELL/4GL Settable

Whenever a clear-to-find operation occurs, allprevious SEARCH_RANGES assignments areoverwritten by the results of the clear-to-findexpressions.

When you modify the SEARCH_RANGES attributefrom the form script, the new value does not appearon the screen form.

Any SEARCH_RANGES assignments in an eventsection that is executed before the ��

command are overwritten when the�� assigns the values of theclear-to-find expressions to the associatedSEARCH_RANGES attributes. You can clear theSEARCH_RANGES value by assigning azero-length string to it.

Data type String

Valid values clear-to-find expressionDefault: zero-length string

��

��

��

�#��"��

�#��

Summary

Related Attributes


explicit_mode$( )“Find Mode” in ��

For graphical user interfaces only, the SELECTED_SET_SCROLLBAR attribute specifies the location of the scroll bar. Thisattribute has no effect in character mode applications.

SELECTED_SET_SCROLLBAR Form Attribute

ACCELL/Generator Form: Form DefinitionField: Selected Set Scroll bar


Data type String

Valid values LEFTRIGHTNONE

��*�$��$�� ) ��+��$�&��

See Also

SELECTED_SET_SCROLLBAR

Summary

See Also


The SQL_COLUMN_CONDITION attribute contains a string expressionthat specifies the search criteria for a database table column. Thisattribute is redefined whenever search criteria are entered on the form orwhen the SEARCH_RANGES attribute is set. It is cleared whenever aclear-to-find operation clears the search ranges. This attribute has noeffect in add/update/delete mode.

SQL_COLUMN_CONDITION Target Variable Attribute


ACCELL/4GL SettableStandard form scripts only.

Data type String

Valid values A string enclosed within a pair of apostrophes (’).The string can include any expression allowed by thedatabase within the WHERE clause of a SELECTstatement.

��

��

�#��

“Find Mode” in ��

The SQL_OPTIONAL_CONDITION attribute specifies an optionalcondition for an interactive find operation. This attribute is not affectedby user actions.


SQL_OPTIONAL_CONDITION Form Attribute

ACCELL/Generator Form: Form DefinitionField: Optional Condition


Data type String


SQL_COLUMN_CONDITION

Summary

Related Attributes

See Also

SQL_OPTIONAL_CONDITION

Summary


SQL_WHERE_CLAUSE


The SQL_ORDER_BY_CLAUSE attribute specifies the ORDER BYclause condition for an interactive find operation. This attribute isredefined whenever the SQL_ORDER_BY_COLUMN attribute is set.


SQL_ORDER_BY_CLAUSE Form Attribute



Data type String

Valid values A string enclosed within a pair of single quotationmarks (’). The string can include any expressionallowed by the database within the ORDER BYclause of a SELECT statement.

SQL_ORDER_BY_COLUMN


The SQL_ORDER_BY_COLUMN attribute is a one-dimensional array ofeight elements that specifies the column name and sorting order ofrecords in form fields. Each of the eight attribute elements is identifiedby a subscript, for example:

SET SQL_ORDER_BY_COLUMN[1] TO ’co_key ASCENDING’;

Setting this attribute causes the SQL_ORDER_BY_CLAUSE attribute tobe redefined.


Related Attributes

See Also

SQL_ORDER_BY_CLAUSE

Summary

Related Attributes

See Also

SQL_ORDER_BY_COLUMN


If this attribute is not set, records are retrieved from the database in theorder in which they are stored.

SQL_ORDER_BY_COLUMN Form Attribute

ACCELL/Generator Form: Form DefinitionField: Sort Field


Data type String

Valid values A string enclosed within a pair of single quotationmarks (’)Sorting order must be specified as one of thefollowing:ASCENDING DESCENDING

SQL_ORDER_BY_CLAUSE


Summary

Related Attributes

See Also


The SQL_WHERE_CLAUSE attribute contains the WHERE clause for aninteractive find operation. This attribute is redefined whenever theSEARCH_RANGES, SQL_COLUMN_CONDITION, orSQL_OPTIONAL_CONDITION attributes are assigned.


SQL_WHERE_CLAUSE Form Attribute



Data type String


�#��"��

�#��

��


When the STOP_FOR_INPUT attribute is set to TRUE, execution pauseson the field to accept user input.

STOP_FOR_INPUT Field Attribute

ACCELL/Generator Form: Field DefinitionField: Stop For Input

ACCELL/4GL SettableThe setting of this attribute has no effect onexecution of ACCELL/4GL Field event sections(BEFORE FIELD, ON FIELD, etc.). Field sectionsare executed whenever the form is in add/updatemode, regardless of the setting of this attribute.

Data type Boolean


SQL_WHERE_CLAUSE

Summary

Related Attributes

See Also

STOP_FOR_INPUT

Summary


FINDABLEFIRST_FIELDREQUIRED


When the TAB_STOP attribute is set to TRUE, the field is tab-stopped.When the user presses �� or ��, the user canquickly skip fields that are not tab stopped.

TAB_STOP Field Attribute

ACCELL/Generator Form: Field DefinitionField: Tab Stop

ACCELL/4GL SettableThe setting of this attribute has no effect onexecution of ACCELL/4GL Field event sections(BEFORE FIELD, ON FIELD, etc.). Field sectionsare executed whenever the form is in add/updatemode, regardless of the setting of this attribute.

Data type Boolean


STOP_FOR_INPUT


The TARGET_FIELD attribute specifies the name of the target field’sdatabase column.

TARGET_FIELD Target Variable Attribute



Data type String

Valid values The name of a target table field

Related Attributes

See Also

TAB_STOP

Summary

Related Attributes

See Also

TARGET_FIELD

Summary


The TARGET_TABLE attribute specifies the name of the form’s targettable. A target table is optional for a Standard form.

TARGET_TABLE Form Attribute

ACCELL/Generator Form: Form DefinitionField: Target Table


Data type String

Valid values The name of a database table

FORM in this manual


When the UNDERLINE attribute is set to TRUE, the field display is setfor underlined video.


UNDERLINE Field Attribute

ACCELL/Generator Form: Field DefinitionField: Field Video Attributes: Underline

ACCELL/4GL Settable

Data type Boolean


��$

��

��!��

“Creating Screen Form Fields” in �� (� ��#�$��'�)!�%�$��*�$��$�� ) ��+��$�&��

TARGET_TABLE

Summary

Related Attributes

See Also

UNDERLINE

Summary

Related Attributes

See Also


When the UPDATE_ALLOWED attribute is set to TRUE, the user haspermission to perform interactive update operations on the form’s targettable. The form must have a target table.

ACCELL/Manager notifies the user if an attempt is made to perform anoperation for which the user does not have form access privilege.

UPDATE_ALLOWED Form Attribute

ACCELL/Generator Form: Form DefinitionField: Update Allowed

ACCELL/4GL Settable

Data type Boolean


��

��

��

SET, update_allowed$ in this manual“Creating Screen Forms” in �� AMGR in �� ! ��"� ��#$��%�&��$��'��

If the UPDATEABLE attribute is set to FALSE and STOP_FOR_INPUT isTRUE, the user can stop on the field, scroll through the field, or zoom toanother form. However, the contents of the field cannot be changed.

UPDATEABLE Field Attribute

ACCELL/Generator Form: Field DefinitionField: Updateable

ACCELL/4GL Settable

Data type Boolean


AUTO_EDIT


UPDATE_ALLOWED

Summary

Related Attributes

See Also

UPDATEABLE

Summary

Related Attributes

See Also


For graphical user interfaces only, specifies whether a standard formis created as a base window. This attribute has no effect in charactermode applications.

USE_BASE_WINDOW Form Attribute

ACCELL/Generator Form: Form DefinitionField: Use Base Window


Data type Boolean


��*�$��$�� ) ��+��$�&��

The WIDTH attribute specifies the width of a screen form in columns.

WIDTH Form Attribute

ACCELL/Generator Settable with the �� command


Data type Numeric

Valid values Integer greater than or equal to 1Default: 60

��

��


USE_BASE_WINDOW

Summary

See Also

WIDTH

Summary

Related Attributes

See Also


The WINDOW_HEIGHT attribute specifies the height of a TEXT field onthe screen. For other types of fields, this attribute value must be 1.

WINDOW_HEIGHT Field Attribute

ACCELL/Generator Form: Field DefinitionField: Window Size

ACCELL/4GL Settable

Data type Numeric

Valid values Integer greater than or equal to 0, up to the maximumavailable on the formDefault: 1

WINDOW_WIDTH


The WINDOW_WIDTH attribute specifies the width of the field on thescreen.

WINDOW_WIDTH Field Attribute

ACCELL/Generator Form: Field DefinitionField: Window Size

ACCELL/4GL Settable

Data type Numeric

Valid values Integer greater than or equal to 0, up to the maximumavailable on the formDefault: Set by the Session Defaults form

WINDOW_HEIGHT


WINDOW_HEIGHT

Summary

Related Attributes

See Also

WINDOW_WIDTH

Summary

Related Attributes

See Also

95

ACCELL/4GL SyntaxDescriptions

��

��

96 ACCELL/4GL Syntax Descriptions

�

��

This chapter contains complete descriptions of all ACCELL/4GL formscript event sections and statements, as well as SQL statements. Thedescriptions appear in alphabetical order and include several parts:

Indicates the beginning of a syntax description.

Indicates a continuation of the description.

Category The category, or type, of statement is shown beneath thesection name. For event sections the type of form wherethe section is valid is also specified, as well asdependencies, if any.

Syntax Presents the syntax for the section or statement.BOLDFACE words are keywords. Shaded areas indicatefeatures that are restricted to a particular user interface,operating system, or RDBMS. Italicized words within thesyntax are described under Arguments.

Support Describes restrictions or dependencies, if any.

Arguments Describes the italicized arguments shown in the syntax.

Description Describes usage, conditions, and notes.

AffectedStatements

Lists restrictions on usage with ACCELL/4GLstatements.

AffectedSections

Lists restrictions on usage within ACCELL/4GL eventsections.

Example Gives a sample that shows how the statement might beused.

See Also Lists other sections, statements, attributes, or manualsthat are related to the statement.

97ACCELL/4GL Syntax Descriptions

AFTER ADD

Add section Standard form script only

��

��

statements ACCELL/4GL statements. See Affected Statements for statementrestrictions.

ACCELL/Manager executes the AFTER ADD section after the completion of aninteractive add operation initiated when the user presses �� and thecurrent record on the form does not have a row in the database. An interactive addoperation initiated by the UPDATE CURRENT RECORD, or UPDATE SELECTEDROW, or SQL INSERT statement does not execute the BEFORE ADD and AFTERADD sections.

The AFTER ADD section is executed regardless of whether the add operation issuccessful. If the interactive add successfully adds a target table row, AFTER ADD isexecuted immediately after the operation is completed.

You can use AFTER ADD to check the success of the interactive add, to increment acount of the number of rows added, to update totals, or to perform validity checking.You can use the status$( ) system function to determine whether the interactive addoperation is successful.

The following statements are invalid in this section:

��

��

��

��

��!��

��!��

��"��

��

��"��#��

��"��#��

��"� ��$��"#��

��"� ��$��"#��

BEFORE ADD, CLEAR TO ADD, NEXT ACTION, ON CLEAR TO ADD, UPDATECURRENT RECORD, UPDATE SELECTED ROW

Syntax

Arguments

Description

AffectedStatements

See Also


�

AFTER APPLICATION

Application section Master application form script only

��

��


ACCELL/Manager executes the AFTER APPLICATION section when the user presses�� from the master application form. AFTER APPLICATION isexecuted after the completion of the ON PREVIOUS FORM section.

If the master application form does not have any form fields with theSTOP_FOR_INPUT attribute set to TRUE, the AFTER APPLICATION section isnever executed.

If the master application form does have STOP_FOR_INPUT form fields, this sectionis not executed when:

the user presses ��

the NEXT ACTION IS EXIT statement is executed

the CHOOSE FIRST FORM statement with the USING EXIT clause isexecuted

the CHOOSE NEXT FORM statement with the USING EXIT clause is executed

the EXIT statement is executed

If you want this section to be executed whenever the user leaves the application, youmust remove the �� command from the unicap file.

The AFTER APPLICATION section can be used to perform actions at the end of anapplication, such as updating counts, displaying messages, or displaying summarystatistics.

Syntax

Arguments

Description


AFTER APPLICATION


��

��

��

��

��

��

��!��

��!��

��"��

��

� ��

APPLICATION, BEFORE APPLICATION, EXIT, ON EXIT

AffectedStatements

See Also


�

AFTER DELETE

Delete section Standard form script only

��

��


ACCELL/Manager executes the AFTER DELETE section after the completion of aninteractive delete operation initiated when the user presses ��. Aninteractive delete operation initiated by the DELETE CURRENT RECORD, DELETESELECTED ROW, or SQL DELETE statement does not execute the BEFOREDELETE and AFTER DELETE sections.

The AFTER DELETE section is executed regardless of whether the interactive deleteoperation is successful. If the interactive delete operation successfully deletes a targettable row, AFTER DELETE is executed immediately after the operation is completed.

In the AFTER DELETE section you can check the success of the database deleteoperation, count the number of rows deleted, and update other totals. You can use thestatus$( ) system function to determine whether the interactive delete operation wassuccessful.


��

��

��

��

��!��

��!��

��"��

��

��"��#��

��"��#��

��"� ��$��"#��

��"� ��$��"#��

BEFORE DELETE, DELETE CURRENT RECORD, DELETE SELECTED ROW,NEXT ACTION

Syntax

Arguments

Description

AffectedStatements

See Also


AFTER FIELD

Field section Master application and standard form scripts

��

��

��

�� %��%��&�"

��

��

�


ACCELL/Manager executes the AFTER FIELD section as the final step in theprocessing of a form field. This is the final section executed before ACCELL/Managergoes on to another field on the form.

The AFTER FIELD section is a subsection of the FIELD section. You must introducethe AFTER FIELD subsection with the FIELD section. The FIELD section identifiesthe particular form field to which the AFTER FIELD section refers.

Only one FIELD section is required per form field.

This subsection usually contains statements to process accepted input data. You canuse AFTER FIELD to redisplay entered data in a different format or to set defaultvalues if the user enters nothing in the field.

However, in the AFTER FIELD subsection, you cannot allow the user to reenter inputif a validity check fails. To restart input, you must use the RESTART ON FIELDstatement in the ON FIELD subsection.

Syntax

Arguments

Description


�

AFTER FIELD


��

��

��

��

In this example, if the user has moved to the next field without completing theship_code field, a null value is assigned to the ship_code field.

FIELD ship_codeAFTER FIELD

IF ( $ship_code IS UNDEFINED ) THENSET $ship_code TO NULL

BEFORE FIELD, FIELD, INIT FIELD, NEXT ACTION, ON FIELD, WHEN FIELDCHANGES

AffectedStatements

Example

See Also


AFTER FIND

Find section Standard form script only

��

��


ACCELL/Manager executes the AFTER FIND section after the completion of aninteractive find operation. An interactive find operation occurs when:


the NEXT ACTION IS FIND statement is executed

the form begins execution with AUTO_FIND set to TRUE (andAUD_ON_ENTRY set to FALSE)

The AFTER FIND section is executed regardless of whether the interactive findoperation is successful. AFTER FIND is executed immediately after the operation iscompleted.

A noninteractive find operation initiated by the SQL SELECT statement does notinvoke the BEFORE FIND, ON FIND, and AFTER FIND sections.

In the AFTER FIND section you can check the status of the database search, updatetotals, perform validity checking, and count the number of records found. TheACCELL/SQL system function current_record_count$( ) determines how manyrecords have been found. You can use the status$( ) system function to determinewhether the interactive find operation was able to search the target table successfully.

Syntax

Arguments

Description


�

AFTER FIND


��

��

��

��

��!��

��!��

��"��

��

��"��#��

��"��#��

��"� ��$��"#��

��"� ��$��"#��

BEFORE FIND, NEXT ACTION, ON CLEAR TO FIND, ON FIND,REJECT RECORD

AffectedStatements

See Also


AFTER FORM RETURN

Form section Master application and standard form scripts

��

��


ACCELL/Manager executes the AFTER FORM RETURN section when executionreturns from a next form. When the user presses �� from a form,ACCELL/Manager first completes the ON PREVIOUS FORM section in the currentform’s script and then deactivates the current form. The form that was the previousform becomes the current form again.

When the user presses �� from a zoom form, ACCELL/Manager firstcompletes the AFTER ZOOM section in the zoom form script and then deactivatesthe zoom form. The calling form (the form where the �� was initiated) is now thecurrent form again.

On this new current form, ACCELL/Manager executes AFTER FORM RETURNregardless of whether the user has pressed �� from a zoom form orfrom a next form. After the AFTER FORM RETURN section is completed,ACCELL/Manager returns to the ON FIELD subsection that was suspended when theuser pressed either �� (to a next form) or �� (to a zoom form) andbegins execution from the beginning of ON FIELD.

The AFTER FORM RETURN section can be used to determine what actions to takewhen the user returns to a previous form.

Syntax

Arguments

Description


�

AFTER FORM RETURN


��

��

��

��

��!��

��!��

��"��

��

��"��#��

��"��#��

��"� ��$��"#��

��"� ��$��"#��

In this Order/Items application, returning from a next form signifies that you havecompleted an order.

FORM fordersTARGET_TABLE order

AFTER FORM RETURNIF ( yesno$( ’Enter a new order?’ , –1) ) THEN

BEGINUPDATE CURRENT RECORDNEXT ACTION IS CLEAR_TO_ADD

END

AFTER ZOOM, BEFORE FORM, ON NEXT FORM, ON PREVIOUS FORM

AffectedStatements

Example

See Also


AFTER UPDATE

Update section Standard form script only

��

��


ACCELL/Manager executes the AFTER UPDATE section after the completion of aninteractive update initiated when the user presses �� and the currentrecord on the form already has a row in the database. An interactive update operationinitiated by the UPDATE CURRENT RECORD statement does not execute theBEFORE UPDATE and AFTER UPDATE sections.

The AFTER UPDATE section is executed regardless of whether the operation issuccessful. If the operation is successful, AFTER UPDATE is executed immediatelyafter the operation is completed.

A noninteractive update initiated by the SQL UPDATE statement does not invoke theBEFORE UPDATE and AFTER UPDATE sections.

In the AFTER UPDATE section you can check the success of the database update,count the number of rows modified, update totals, and perform validity checking.You can use the status$( ) system function to determine whether the interactiveupdate was successful.

Syntax

Arguments

Description


�

AFTER UPDATE


��

��

��

��

��!��

��!��

��"��

��

��"��#��

��"��#��

��"� ��$��"#��

��"� ��$��"#��

BEFORE UPDATE, CLEAR TO ADD, NEXT ACTION, UPDATE SELECTED ROW

AffectedStatements

See Also


AFTER ZOOM


��

��


ACCELL/Manager executes the AFTER ZOOM section when the user presses�� on a zoom form. On the zoom form, ACCELL/Manager executesAFTER ZOOM in the zoom form’s script; then it deactivates the zoom form andreturns to the calling form. On the calling form, ACCELL/Manager resumes executionwith the AFTER FORM RETURN section.

ACCELL/Manager does not execute the AFTER ZOOM section when one of theseevents occurs:

The user presses �� from a next form; instead, it executes onlythe ON PREVIOUS FORM section.

The user presses �� from a zoom form.

You can use AFTER ZOOM to set global variables or values as a way of bringingadditional information back from the zoom form. If you have several zoom formsenabled for a single form, you can set a global variable in AFTER ZOOM thatidentifies the particular zoom form. You can then use this variable in the AFTERFORM RETURN section to determine the appropriate action to take for the zoomform that executed.

Syntax

Arguments

Description


�

AFTER ZOOM


��

��

��

��

��!��

��!��

��"��

��

��"��#��

��"��#��

��"� ��$��"#��

��"� ��$��"#��

AFTER FORM RETURN, ENABLE ZOOM, ON NEXT FORM,ON PREVIOUS FORM

AffectedStatements

See Also


ALTER SCHEMA

SQL DDL statement RDBMS dependent

��"%�� '

This statement must conform to the syntax specified by the RDBMS.

schema_name The name of a database schema. If not specified, the user’s defaultschema is used.

DDL_statementsAny of the DDL statements allowed by the RDBMS within an ALTERSCHEMA command. If more than one statement is listed, thestatement list must be enclosed by a pair of parentheses.

The ALTER SCHEMA statement changes object definitions for a schema, includingtable, column, index, and privilege specifications.

When ACCELL/Manager encounters this statement, it prepares the statement forprocessing by the database. Because this statement is executed by the RDBMS, it mustconform to the syntax requirements of the RDBMS; extensions provided by theRDBMS can also be included.

ACCELL/SQL variables can be used as parameters within this statement but must beprefixed by a dollar sign ($). Do not enclose this statement within a BEGIN_SQL andEND_SQL statement block.

This statement can be used in all ACCELL/4GL event sections.

This statement drops the curr_sales view from the sales schema of the database.

ALTER SCHEMA sales DROP VIEW curr_sales;

DROP SCHEMA��Documentation provided by the RDBMS vendor

Syntax

Support

Arguments

Description

AffectedSections

Example

See Also


�

ALTER TABLE


�� (�� !��")�� #��*"'



table_name The name of a database table.

alter_table clauseAny of the clauses allowed by the RDBMS within an ALTER TABLEcommand.

The ALTER TABLE statement changes the definition of a database table.




This statement renames two columns of the part_master table.

ALTER TABLE part_master (RENAME COLUMN part_desc TO part_descriptionRENAME COLUMN level TO part_level);

DROP TABLE��Documentation provided by the RDBMS vendor

Syntax

Support

Arguments

Description

AffectedSections

Example

See Also


APPLICATION

Required application header Master application form only

��

�� $��

��"��%+��"�� #��&'�� #��&'�

��"��&��#��&'��,

��%+��"�� #��&'�� #��&'�

��"��&��#��&'��-��"��#��&'��#��&'��,

APPLICATION application_name[ ARCHIVES ’archive_name’ [ , ’archive_name’ ] . . . ][ REQUIRED FORMS

[ form_name [ IN ’archive_name’ [ [ cache_spec ] ] . . . ][ REQUIRED FUNCTIONS

[ function_name [ IN ’archive_name’ [ [ cache_spec ] ] . . . ]

�-�

�-�

application_nameThe name of the application. This name must match the form nameof the master application form as defined in ACCELL/Generator.

form_name The name of a standard form in the application. This form namemust match the standard form name defined in ACCELL/Generatorand in the form script.

function_name The name of a global ACCELL/4GL function used in the application.This function name must match the function name as it is defined inthe global function script file.

Syntax

Arguments


�

APPLICATION

archive_name The name of the archive file where a form or function is stored. Thearchive file is the archive name given to the ACCELL/SQL combinerutility, ACMB. When searching for a form or function, the list ofarchive files is searched in the order given in the ARCHIVESdeclaration; if not found, the default archive is then searched. Thedefault archive name is application_name.fa.

cache_spec (Optional) One of the following cache persistence specifiers:

CACHED (Default) On form deactivation, the form or functionis placed in cache if space is available. If that spacebecomes unavailable, the function will automaticallybe removed from cache.

UNCACHED The form or function is not placed in cache.

LOCKED_IN_CACHEIf space is available, the form or function is placed incache upon activation and remains there throughoutexecution of the application.

Cache usage of ACCELL/Manager is determined by the settings of theAMGR_FORM_CA_SZ and AMGR_FUNC_CA_SZ configurationvariables. For further information about configuration variables, see��#��(�� )��%�� . Forinformation about cache management, see ��'' ��.

scalar_variable A comma-separated list of variable names that are local variables inthis form.

The APPLICATION section is required as the first section after function declarationsin the master application form script. This section defines the application name, theapplication archives, the application forms, and the application functions (globalACCELL/4GL functions).

By default, all compiled application forms and functions are combined in an archivefile named application_name.fa. If your application does not use the default .fa file,or if your application uses additional archive files, such files must be listed in eitherthe ARCHIVES clause or one of the REQUIRED clauses.

Description


APPLICATION

The ARCHIVES clause lists the names of archive (.fa) files that contain applicationforms and functions. This statement is required for any application that has forms orfunctions that are not contained in the default application_name.fa file or that are notlisted in a REQUIRED clause with an archive_name specification. The ARCHIVESclause specifies the order to be used by the linker (ALNK) when archives aresearched for linking each script into the application.

If the specified archive files contain duplicate form or function names, theACCELL/SQL linker chooses the first one that contains the form or function. List themost often referenced archive files first. If there is no REQUIRED clause, the defaultarchive is searched first, and then the ARCHIVES list is searched. If theACCELL/SQL linker cannot find a form or function in any of the archive files, itdisplays a warning message and continues creating the application link (.al) file. Youcan override the ARCHIVES clause and the default file by explicitly specifying thecorrect form or function with an IN ’archive_name’ phrase in a REQUIRED clause.

A REQUIRED FORMS clause is required for any form that the application referencesby string expression rather than by form name. It is also required if a particular formis not included either in the default archive file or in one of the archive files listed inthe ARCHIVES clause.

For example, the following statement determines the form name at runtime:

SET formname TO ’localtrim’...DISPLAY TRIM FOR formname

To ensure that the localtrim form is displayed at runtime, the following statementmust be included in the APPLICATION section:

REQUIRED FORMSlocaltrim IN ’hawaii.fa’


�

APPLICATION

The REQUIRED FUNCTIONS clause lists global functions used in the application.Each global function is written in a separate ACCELL/4GL script (.fs) file; however,these .fs files do not have matching .fq files. You must compile and combine theglobal scripts into an archive file. This clause is required for any function that is notcontained either in the default archive file or in one of the archive files listed in theARCHIVES clause.

Use the REQUIRED FUNCTIONS clause to specify an archive file different from thedefault archive or archive listed in the ARCHIVE clause, for instance, for a functionthat has a duplicate name.

An error occurs if the ACCELL/SQL linker cannot find a REQUIRED form orfunction in the archive file that is explicitly specified by an IN ’archive_name’phrase.

The LOCAL clause lists the names of variables that are local to this form. Localvariables can be accessed by just the variable name; they do not need to be prefixedwith the form name (form_name:variable) to clarify which form they are defined on.Local variables can be referenced by successive forms.

The LOCAL clause can also be used to declare a one- or two-dimensional array. Youcan specify the lower and upper subscript bounds for each dimension of an array. Thebounds of the array must be enclosed by brackets—[ ]. LIST indicates aone-dimensional array. MATRIX indicates a two-dimensional array. The bounds of anarray can be specified by any expression that is equivalent to an integer. To optimizememory usage, you can use a variable to dynamically declare the bounds when aform is activated.

The lower bounds of an array can be any positive or negative integer, up to themaximum allowed by your operating system for long integers. By default, the lowerbound is 1.

For an unbounded array, use the keyword UNKNOWN to indicate that the upper limitof a row is unknown or unlimited. You can specify an estimated upper bound byusing the phrase UNKNOWN ESTIMATING numeric expression. By default, if theestimating clause is omitted, the estimated upper bound is 100.

To verify whether an array has an upper bound, use the BOUNDED attribute. Todetermine the type of an array, use the DIMENSION attribute.


APPLICATION

This APPLICATION section defines the ACCELL/SQL application payroll. All formsare contained in the default archive file, payroll.fa. Two archive files, functions.faand globals.fa, contain a function named calculate_pay; the function definitionneeded for this application is contained in globals.fa.

APPLICATION payrollARCHIVES ’functions.fa’, ’globals.fa’REQUIRED FUNCTIONS

calculate_pay IN ’globals.fa’

AFTER APPLICATION, BEFORE APPLICATION, FORM, FUNCTION��#��(�� )��%�� '' ��

Example

See Also


�

BEFORE ADD

Add section Standard form script only

��

��


ACCELL/Manager executes the BEFORE ADD section as the first step of aninteractive add initiated when the user presses �� and the current recordon the form does not have a row in the database. Before the interactive add actuallyattempts to add the new target table row, ACCELL/Manager executes BEFORE ADD.

An interactive add initiated by the UPDATE CURRENT RECORD statement or anSQL INSERT statement does not invoke the BEFORE ADD and AFTER ADDsections.

You can abort the requested interactive add operation by using the REJECTOPERATION statement in this section.

In the BEFORE ADD section you can log the user who is adding specific rows,provide additional security constraints, initialize totals, or verify that the user doeswant to do an add operation before performing the add.


��

��

��

��

��!��

��"��

��

��"��#��

��"��#��

��"� ��$��"#��

��"� ��$��"#��

AFTER ADD, CLEAR TO ADD, NEXT ACTION, ON CLEAR TO ADD,REJECT OPERATION, UPDATE CURRENT RECORD

Syntax

Arguments

Description

AffectedStatements

See Also


BEFORE APPLICATION

Application section Master application form script only

��

��


ACCELL/Manager executes the BEFORE APPLICATION section as the first step inthe application initialization. After executing BEFORE APPLICATION,ACCELL/Manager displays the master application form and executes any INIT FIELDsubsections in the master application form script’s FIELD sections. As a final step,ACCELL/Manager executes the BEFORE FORM section in the master applicationform script.

The BEFORE APPLICATION section can be used to perform actions at the beginningof an application, such as establishing a user’s identity, initializing application totals,or establishing security constraints.


��

��

��

��

��

��

��!��

��!��

��"��

��

� ��

AFTER APPLICATION, APPLICATION, BEFORE FORM, INIT FIELD

Syntax

Arguments

Description

AffectedStatements

See Also


�

BEFORE DELETE

Delete section Standard form script only

��

��


ACCELL/Manager executes the BEFORE DELETE section as the first step of aninteractive delete operation initiated when the user presses �� orwhen the NEXT ACTION IS DELETE statement is executed. Before the interactivedelete actually attempts to delete the target table row, ACCELL/Manager executesBEFORE DELETE.

An interactive delete operation initiated by the DELETE CURRENT RECORDstatement or an SQL DELETE statement does not invoke the BEFORE DELETE andAFTER DELETE sections.

You can abort a requested interactive delete operation by using the REJECTOPERATION statement in this section.

In the BEFORE DELETE section you can log the user who is deleting specific rows,provide additional security constraints, initialize totals, or verify that the user doeswant to do a �� before performing the delete.


��

��

��

��

��!��

��"��

��

��"��#��

��"��#��

��"� ��$��"#��

��"� ��$��"#��

AFTER DELETE, NEXT ACTION, REJECT OPERATION

Syntax

Arguments

Description

AffectedStatements

See Also


BEFORE FIELD


��

��

��

�� *�*�*��

�%��%��&�"��


In add/update/delete mode, ACCELL/Manager executes the BEFORE FIELD sectionimmediately after the cursor stops on a form field. This section is executed either justbefore the user inputs data in the field or just after the user presses �� .User input is not allowed during execution of this section.

The BEFORE FIELD section is a subsection of the FIELD section. You mustintroduce the BEFORE FIELD subsection with the FIELD section. The FIELDsection identifies the particular form field to which the BEFORE FIELD sectionrefers.

If your form script includes a FIELD section for the field for one of the other FIELDsubsections, do not repeat the FIELD section. Only one FIELD section is required perform field.

If the FIELD section does not contain an ON FIELD subsection, ACCELL/Managerautomatically performs an INPUT statement after completing the BEFORE FIELDsubsection. The INPUT statement allows the user to enter data in the form field. If theFIELD section does contain ON FIELD, the INPUT statement is not automaticallyperformed.

Syntax

Arguments

Description


�

BEFORE FIELD

You can use this section to initialize appropriate variables. You can also prevent inputby setting the field’s STOP_FOR_INPUT attribute to FALSE in this section.

This section has no effect in find mode.


��

��

��

��!��

��!��

��"��

��

AFTER FIELD, BEFORE RECORD, ENABLE ZOOM, FIELD, INIT FIELD,NEXT ACTION, ON FIELD, WHEN FIELD CHANGES

AffectedStatements

See Also


BEFORE FIND

Find section Standard form script with target table only

��

��


ACCELL/Manager executes the BEFORE FIND section as the first step of aninteractive find. An interactive find occurs when:


the NEXT ACTION IS FIND statement is executed

the form begins execution with AUTO_FIND set to TRUE (andAUD_ON_ENTRY set to FALSE)

Before the interactive find actually attempts to search the target table,ACCELL/Manager executes BEFORE FIND. If the interactive find is initiated withNEXT ACTION IS FIND, BEFORE FIND is executed after ON CLEAR TO FIND.

A noninteractive find initiated with the SELECT statement can also search databasetables. However, it does not invoke the BEFORE FIND, ON FIND, and AFTER FINDsections.

You can abort a requested interactive find operation by using the REJECTOPERATION statement in this section.

Syntax

Arguments

Description


�

BEFORE FIND

In the BEFORE FIND section, you can specify additional search criteria by setting theSQL_OPTIONAL_CONDITION, SQL_ORDER_BY_COLUMN andSEARCH_RANGES attributes of appropriate variables. Assigning search values to thevariables themselves does not establish search criteria at this point, becauseACCELL/Manager uses search ranges, not variable values, when selecting records.

In the BEFORE FIND section you can log the user who is searching for specific rows,provide additional security constraints, initialize totals, or verify that the user doeswant to do a find operation before performing the search.


��

��

��

��

��!��

��!��

��"��

��

��"��#��

��"��#��

��"� ��$��"#��

��"� ��$��"#��

AFTER FIND, NEXT ACTION, ON FIND, ON CLEAR TO FIND,REJECT OPERATION, REJECT RECORD“Attributes” chapter of this manual“Find Mode” in ��+��,�� '��

AffectedStatements

See Also


BEFORE FORM


��

��


ACCELL/Manager executes the BEFORE FORM section after the form is initializedbut before any fields are executed. To initialize a form, ACCELL/Manager displaysthe form and then executes any INIT FIELD subsections in the form script’s FIELDsections.

You can use the BEFORE FORM section to perform any necessary forminitializations before the form execution begins. Common initialization tasks areselecting the form mode, and setting variable and attribute values.

In a master application form script, BEFORE FORM is executed after the forminitialization is completed and after the BEFORE APPLICATION section is executed.


��

��

��

��

��

��!��

��!��

��"��

��

AFTER FORM RETURN, BEFORE APPLICATION, INIT FIELD

Syntax

Arguments

Description

AffectedStatements

See Also


�

BEFORE RECORD

Record section Standard form script only

��

��


The BEFORE RECORD section is executed when a new record is made current. Arecord in a selected set can be made current in two ways:

by using one of the �� record commands, such as ��

or ��

by executing ACCELL/4GL statements, such as NEXT ACTION and QUEUECOMMAND

You can use the BEFORE RECORD section to perform tasks that must be done oncefor each record.

The BEFORE RECORD section is executed just before the BEFORE FIELD sectionassociated with the first field of the record.

This section is not executed when the attempt to make a new record current fails, forexample, when the record has been deleted or when the user executes the�� command from the last record of the selected set.


��

��

��

��!��

��!��

��"��

��

��"��#��

��"��#��

��"� ��$��"#��

��"� ��$��"#��

BEFORE FIELD, NEXT ACTION, ON NEXT FORM, QUEUE COMMAND

Syntax

Arguments

Description

AffectedStatements

See Also


BEFORE UPDATE

Update section Standard form script only

��

��


ACCELL/Manager executes the BEFORE UPDATE section as the first step of aninteractive update operation initiated when the user presses �� and thecurrent record on the form already has a row in the database or when NEXT ACTIONIS ADD_UPDATE is executed. Before the interactive update actually attempts toupdate the target table row, ACCELL/Manager executes BEFORE UPDATE.

An interactive update operation initiated by the UPDATE CURRENT RECORDstatement or an SQL UPDATE statement does not invoke the BEFORE UPDATE andAFTER UPDATE sections.

You can abort a requested interactive update operation by using the REJECTOPERATION statement in this section.

In the BEFORE UPDATE section, you can log which users modify specific records,provide additional security constraints, initialize totals, and verify that the user doeswant to perform an update operation before performing the update.

Syntax

Arguments

Description


�

BEFORE UPDATE


��

��

��

��

��!��

��"��

��

��"��#��

��"��#��

��"� ��$��"#��

��"� ��$��"#��

AFTER UPDATE, REJECT OPERATION

AffectedStatements

See Also


BEGIN_SQL

SQL block statement

��&��#".�

The BEGIN_SQL statement marks the start of an SQL statement block. This statementis required for executing nonstandard database statements, such as vendor-specificextensions.

This statement is not required for DML and DDL statements.

The SQL statement block must be terminated by the END_SQL statement.

The database statements listed between the begin and end delimiters are sent directlyto the database for processing. ACCELL/SQL variables can be used within thestatement block, but the database cannot return values to the ACCELL/SQLapplication. The BEGIN_SQL and END_SQL statements themselves are not passed tothe database.

If the RDBMS does not permit DDL statements within a transaction, use thetx_mode$( ) system function and the COMMIT WORK statement to terminate thecurrent transaction before execution of the SQL statement block.


Syntax

Description

AffectedSections


�

BEGIN_SQL

The following example shows how the BEGIN_SQL and END_SQL statements areused to enclose SYBASE SQL Server statements.

create table NEXTNUM(NXT_FIELD_NAME char(15),NXT_NUMBER int);

COMMIT WORK

BEGIN SQLinsert into NEXTNUM (NXT_FIELD_NAME, NXT_NUMBER)

VALUES (’CO_KEY’,$inival)insert into NEXTNUM (NXT_FIELD_NAME, NXT_NUMBER)

VALUES (’ORD_NUMBER’,$inival)insert into NEXTNUM (NXT_FIELD_NAME, NXT_NUMBER)

VALUES (’EMP_KEY’,$inival)insert into NEXTNUM (NXT_FIELD_NAME, NXT_NUMBER)

VALUES (’CT_KEY’,$inival)insert into NEXTNUM (NXT_FIELD_NAME, NXT_NUMBER)

VALUES (’LD_KEY’,$inival)insert into NEXTNUM (NXT_FIELD_NAME, NXT_NUMBER)

VALUES (’ALT_KEY’,$inival)insert into NEXTNUM (NXT_FIELD_NAME, NXT_NUMBER)

VALUES (’NV_NUMBER’,$inival)END_SQL

In this example, the current transaction is terminated before execution of the SQLstatement block.

tx_mode$(FALSE)COMMIT WORKBEGIN_SQL

CREATE VIEW view1 ASSELECT column1, column2 from table1

END_SQLtx_mode$(TRUE)BEGIN WORK

END_SQL

Example

See Also


BEGIN WORK

Transaction statement RDBMS dependent

��"��&��

��&��

connection The keyword DEFAULT or a string expression that specifies thename of a database connection, for example:

USING CONNECTION DEFAULT

or

USING CONNECTION ’emps’

The keyword DEFAULT specifies the default connection that wasspecified for the application. A string expression must match one ofthe entries in the database connection map (DCM) file.

The BEGIN WORK statement starts a transaction. If a transaction already exists or ifautomatic transaction handling is enabled, this statement has no effect.

By default, the ACLTXMODE configuration variable is set to TRUE and ACCELL/SQLautomatically begins and commits transactions. However, if ACLTXMODE is set toFALSE, automatic transaction handling is disabled.

When automatic transaction handling is disabled, the CHOOSE FIRST FORM orCHOOSE NEXT FORM transaction level specifications have no effect. Therefore,you must explicitly begin and commit transactions by using the BEGIN WORK andCOMMIT WORK statements.

You can use the tx_mode$( ) system function to dynamically enable or disableautomatic transaction handling, regardless of the setting of ACLTXMODE.

For INFORMIX with a MODE ANSI database, and for INGRES, ORACLE, or UnifyDataServer, ACLTXMODE and tx_mode$( ) have no effect because automatictransaction handling is always enabled.

Syntax

Arguments

Description


�

The optional USING clause specifies the name of a database connection for thisstatement only. The optional keyword CONNECTION can be used to enhancereadability of the clause. If no connection is specified, the connection of the currentform is used.

This statement can be used in all ACCELL/4GL event sections.AffectedSections


BEGIN WORK

In this example, a new transaction is started and an update operation is processed. Ifthe update operation is successful, the transaction is committed; otherwise, if theoperation is not successful, the transaction is reversed.

BEGIN WORKUPDATE emp SET salary = salary * 1.1;IF (status$()=SS_NORM) THEN

COMMIT WORKELSE

ROLLBACK WORK

CHOOSE FIRST FORM, CHOOSE NEXT FORM, COMMIT WORK, ROLLBACKWORK, tx_mode$( )ACLTXMODE in ��#��(�� )��%��

Example

See Also


�

BREAK

Control break statement

��

The BREAK statement immediately terminates the execution of a loop statement, aSWITCH statement, or an event section. This statement can be placed anywherewithin a form script.

When executed within a FOR, REPEAT, SET/SELECT EXECUTING, or WHILEstatement, the loop is immediately terminated and execution skips to the statementfollowing the loop. The BREAK statement terminates the current loop only.

Similarly, when BREAK is executed within a SWITCH statement, execution skips tothe statement following the END that terminates the SWITCH statement list.

When executed within other statement blocks, the BREAK statement terminates thecurrent event section.

When executed within a function, but outside a loop, the BREAK statement behaveslike a RETURN statement. In this case, BREAK tells ACCELL/Manager to evaluate allresult parameters and exit from the function.

This example checks the hobbies table for the selected employee and determineswhether the employee plays chess. If the employee’s hobby is not chess, the BREAKstatement terminates the report execution.

SET $emp_id TO SELECT emp_id FROM employeeWHERE emp_name = $name

EXECUTINGBEGIN

SET hobby TO SELECT hobby FROM hobbiesWHERE emp_id = $emp_id and hobby = ’chess’

IF STATUS$() <> 0 THENBEGINDISPLAY ’Employee does not play chess; report aborted’

FOR FYI_MESSAGE WAITBREAKEND

WRITE PIPELINE $report $name . . .

END

Syntax

Description

Example


BREAK


CONTINUE, EXECUTING, FOR, REPEAT, SET, WHILE

AffectedSections

See Also


�

BREAKPOINT

Debugging statement

��

None.

When an application is running with �� turned on,the Debugger window is displayed when control reaches the BREAKPOINTstatement.

The BREAKPOINT statement sets a permanent breakpoint in the application. (The � �� command issued from the Debugger window istemporary.) Setting a breakpoint can help you to debug the application while it is inthe development stage.

The BREAKPOINT statement can be detected only by �� . If the same application is executed with the Debugger turned off, thestatement has no effect on application execution.

The BREAKPOINT statement can be used in all ACCELL/4GL event sections.

Syntax

Arguments

Description

AffectedSections


BREAKPOINT

In this example, when execution reaches the BREAKPOINT statement (when the usertries to add a record), the debugger window is displayed automatically if theapplication is executed in debug mode.

BEFORE ADD

SET fcompany:co_address_1:UPDATEABLE to FALSESET fcompany:co_key TO SELECT nxt_number FROM nextnum

WHERE nxt_field_name = ’co_key’

UPDATE nextnum SET nxt_number TO fcompany:co_key + 1WHERE nxt_field_name = ’co_key’

BREAKPOINT

SET $fcompany:redo_contact TO TRUE

�� $�� #��$��'��-��

Example

See Also


CHANGE CURRENT RECORD


��

numeric_expressionA defined, non-null expression for the nth record in the selected set,where the first record has a value of 1. If the number specified isgreater than the number of records in the selected set, an erroroccurs.

The CHANGE CURRENT RECORD statement changes the current record to therecord in the selected set specified by the numeric expression. However, the ONPREVIOUS RECORD and ON NEXT RECORD sections are not executed.

This statement is invalid in the following ACCELL/4GL sections:

��

��

��

��

��

��

��

In this example, the records in the selected set are each sent to the pipeline identifiedby $pipe_one.

CREATE PIPELINE $pipe_one ’RPT script –’,’lpr’FOR (SET $idx TO 1; $idx < current_record_count$(); SET $idx TO $idx + 1)BEGIN

CHANGE CURRENT RECORD TO $idx;WRITE PIPELINE $pipe_one

$co_name, $co_key, $co_state, $co_cityENDCLOSE PIPELINE $pipe_one

current_record_count$( )

Syntax

Arguments

Description

AffectedSections

Example

See Also


�

CHOOSE FIRST FORM

Application section and control statement Master application form script only

��

��

��

��

logical_expressionAny ACCELL/SQL expression that evaluates to TRUE or FALSE. Theexpression is evaluated to see if the form specified by form_name isa candidate first form.

transaction Specifies the transaction level and consistency level. The transactioninformation must be one of the following:

START TX RECORD_CONSISTENCYSTART TX SET_CONSISTENCY START TX NO_CONSISTENCY

The transaction level specification has no effect when automatictransaction handling is disabled.

form_name The name of the first form. This name can either be the literal formname (without quotation marks) or a string expression.

ACCELL/Manager executes the CHOOSE FIRST FORM section when it moves to theapplication’s first form. ACCELL/Manager moves to the first form when it receives anext form command (�� or NEXT ACTION IS NEXT_FORM) from themaster application form. It executes CHOOSE FIRST FORM after the ON NEXTFORM section. The first form is the first standard form in the application; it followsthe master application form.

The CHOOSE FIRST FORM statement overrides any first form specification youmake in ACCELL/Generator on the master application form’s Choose Next Formform. If no CHOOSE FIRST FORM exists, ACCELL/Manager uses the next forminformation defined in ACCELL/Generator.

Syntax

Arguments

Description


CHOOSE FIRST FORM

The USING clause lists the name of the first form. You can either specify anapplication form name or the keyword EXIT. The form name is the name of anexisting standard form in the application. This first form is executed after the masterapplication form.

If the keyword EXIT is in the USING clause, ACCELL/Manager exits the applicationafter the current form. To exit the application, ACCELL/Manager deactivates the firstform, executes the ON EXIT section for the master application form (if one exists),and then ends the application.

The WHEN clause specifies the conditions under which the first form in the USINGclause is executed. If the WHEN clause logical_expression evaluates to TRUE, theUSING clause form is selected as a first form. If this clause evaluates to FALSE, theform is not selected.

You can repeat the WHEN clause to list several possible first forms for theapplication. If several WHEN clauses are TRUE, ACCELL/Manager provides a NextForm menu for the user to select the first form from. If no WHEN clauses evaluate toTRUE, an error message is displayed saying that no next forms are defined.

CHOOSE FIRST FORM also establishes the beginning and end of transactionsthrough the transaction clause.

By default, the ACLTXMODE configuration variable is set to TRUE and ACCELL/SQLautomatically begins and commits transactions. However, if ACLTXMODE is set toFALSE, automatic transaction handling is disabled, and the transaction level clausehas no effect. Therefore, you must explicitly begin and commit transactions by usingthe BEGIN WORK and COMMIT WORK statements.


You can use only the Start Tx transaction level in the CHOOSE FIRST FORMstatement. All other transaction levels (Continue Tx and Restart Tx) are invalid.

Use the CHOOSE NEXT FORM statement in a standard form script to determine thenext form in the application. The CHOOSE FIRST FORM statement is not valid in astandard form script.


�

CHOOSE FIRST FORM

Additional HelpFor more information about the transaction clause, see the description for theCHOOSE NEXT FORM statement in this manual.

All ACCELL/4GL statements are invalid in this section.

This CHOOSE FIRST FORM example obtains the user’s name from the operatingsystem using the user_name$( ) function. If the user’s name is “Alexander”, theapplication begins with the first_form form. If the user’s name is any name otherthan “Alexander”, the application exits. The effect of the statements is to keep anyonewith the wrong user name from running the application.

CHOOSE FIRST FORMWHEN user_name$() < > ’Alexander’

START TX RECORD_CONSISTENCYUSING EXIT;

WHEN user_name$() = ’Alexander’ START TX RECORD_CONSISTENCY USING first_form

BEGIN WORK, CHOOSE NEXT FORM, COMMIT WORK, ON EXIT,ON NEXT FORM, ROLLBACK WORK, SLOCK, UNLOCK, XLOCK, tx_mode$( )ACLTXMODE in �� !��

AffectedStatements

Example

See Also


CHOOSE NEXT FORM

Form section and control statement Standard form script only

��

��

��

��

logical_expressionAny ACCELL/SQL expression that evaluates to TRUE or FALSE. Theexpression is evaluated to see if the form specified by form_name isa candidate next form.

transaction Specifies the transaction operation and consistency level. Thetransaction clause must be one of the following:

CONTINUE TX RECORD_CONSISTENCYCONTINUE TX SET_CONSISTENCYCONTINUE TX NO_CONSISTENCYSTART TX RECORD_CONSISTENCYSTART TX SET_CONSISTENCYSTART TX NO_CONSISTENCYRESTART TX

form_name The name of the next form. This name can either be the literal formname (without quotation marks) or a string expression.

ACCELL/Manager executes the CHOOSE NEXT FORM section when it moves to theapplication’s next form. ACCELL/Manager moves to the next form when it receives anext form command (�� or NEXT ACTION IS NEXT_FORM) from astandard form. It executes CHOOSE NEXT FORM after the ON NEXT FORMsection. The next form follows a standard form.

The CHOOSE NEXT FORM statement overrides any next Form specification youmake in ACCELL/Generator on a standard form’s Choose Next Form form. If noCHOOSE FIRST FORM exists, ACCELL/Manager uses the next form informationdefined in ACCELL/Generator.

Syntax

Arguments

Description


�

CHOOSE NEXT FORM

The USING clause lists the name of the next form. You can specify either anapplication form name or the keyword EXIT. The form name is the name of anexisting standard form in the application. This next form is executed after the currentform.

If the keyword EXIT is in the USING clause, ACCELL/Manager exits the applicationafter the current form. To exit the application, ACCELL/Manager deactivates the nextform, executes the ON EXIT section for the form that was previously active, and thenends the application.

The WHEN clause specifies the conditions under which the next form in the USINGclause is executed. If the WHEN clause’s logical_expression evaluates to TRUE, theUSING clause form is selected as a next form. If this clause evaluates to FALSE, theform is not selected.

You can repeat the WHEN clause to list several possible next forms for a standardform. If several WHEN clauses are TRUE, ACCELL/Manager provides a Next Formmenu for the user to select the next form from. If no WHEN clauses evaluate toTRUE, an error message is displayed saying that no next forms are defined.

Use the CHOOSE FIRST FORM statement in a master application form script todetermine the first form in the application. The CHOOSE NEXT FORM statement isnot valid in a master application form script.

CHOOSE NEXT FORM also establishes the beginning and end of transactionsthrough the transaction clause. The transaction clause has two parts:

transaction level

consistency level

The following paragraphs describe the actions that occur for each type of transactionand consistency level.


CHOOSE NEXT FORM

CONTINUE TX 1. Continue the current transaction at the currenttransaction level.

RESTART TX 1. If permitted by the RDBMS, downgrade all exclusivelocks to shared locks.

2. Commit current transaction.

3. Remove all invocations of any forms back to thespecified next form; the next form has its selected setstill intact.

4. Restart the transaction at the transaction levelspecified for the next form in ACCELL/Generator.

START TX 1. Commit current transaction (if one is active).

2. Release all existing locks held by the currenttransaction.

3. Remove all invocations of forms back to the masterapplication form.

4. Start the transaction at the transaction level specifiedby the transaction clause in CHOOSE NEXT FORMor CHOOSE FIRST FORM.

RECORD_CONSISTENCY 1. All rows satisfying the search criteria are placed inthe selected set regardless of their lock status.

2. Exclusive-locked rows are placed in the selected set.

3. Only the current record is shared-locked; all otherrecords are unlocked.

and the application reads dirtydata

4. The selected set record (for the exclusive-lockedrow) has the values of the database row when theselected set was created. The actual database row may be in the process of being modified ordeleted by another transaction.

or the application does notread dirty data

�� !"#$��

��!"#$��%��


�

CHOOSE NEXT FORM

SET_CONSISTENCY 1. Lock status of records satisfying the search criteria ischecked before the records are placed in the selectedset.

2. Exclusive-locked records are not placed in theselected set.

3. All records in the selected set are shared-locked.

NO_CONSISTENCY 1. All rows satisfying the search criteria are placed inthe selected set regardless of their lock status.

2. Exclusive-locked rows are placed in the selected set.

3. The current record is not shared-locked; all otherrecords are unlocked.

and the application reads dirtydata

4. The selected set record (for the exclusive-lockedrow) has the values of the database row when theselected set was created. The actual database row may be in the process of being modified ordeleted by another transaction.

or the application does notread dirty data

�� !"#$�� !"#$��%��

!� �� "�#�� $�� %��

For INFORMIX SE and SYBASE SQL Server, the ACLTXMODE configuration variableis set to TRUE by default and ACCELL/SQL automatically begins and commitstransactions. However, if ACLTXMODE is set to FALSE, automatic transactionhandling is disabled, and these transaction level specifications have no effect.Therefore, you must explicitly begin and commit transactions by using the BEGINWORK and COMMIT WORK statements.

For INFORMIX SE and SYBASE SQL Server, you can also use the tx_mode$( )system function to dynamically enable or disable automatic transaction handling,regardless of the setting of ACLTXMODE.


CHOOSE NEXT FORM

The ACLTXMODE configuration variable and the tx_mode$( ) system function haveno effect if you are using INFORMIX on a MODE ANSI database, or are usingINGRES, ORACLE, or Unify DataServer. These RDBMSs always automatically starttransactions.

All ACCELL/4GL statements are invalid in this section.

This CHOOSE NEXT FORM example selects company_form as the next form whencompany_name is “Allied Amalgamated.” For company names other than “AlliedAmalgamated”, the user receives the following message:

There is no ’Next form’

CHOOSE NEXT FORMWHEN company_name = ’Allied Amalgamated’ CONTINUE TX SET_CONSISTENCY USING company_form

BEGIN WORK, CHOOSE FIRST FORM, COMMIT WORK, ON EXIT,ON NEXT FORM, RESTART TX, ROLLBACK WORK, SLOCK, UNLOCK, XLOCK,tx_mode$( )ACLTXMODE in �� !��“Enabling Automatic Transaction Handling” in ��!"#$��%��

AffectedStatements

Example

See Also


�

CLEAR COMMAND QUEUE

Command execution statement

�� %��

The CLEAR COMMAND QUEUE statement causes all command requests on thepending command queue to be removed so that they are not executed.

This statement can be executed within any event section, or from a local or globalfunction.

This statement removes all commands from the command queue when the user exitsthe application.

ON EXITCLEAR COMMAND QUEUE

DEFINE COMMAND, QUEUE COMMAND, SET COMMAND

Syntax

Description

AffectedSections

Example

See Also


CLEAR TO ADD


��

The CLEAR TO ADD statement executes a clear-to-add operation; however, it doesnot simulate the �� command. Unlike the NEXT ACTION ISCLEAR_TO_ADD statement, the CLEAR TO ADD statement does not stop executionof the current event section. After completing the clear-to-add operation, executioncontinues in the current section. In addition, the CLEAR TO ADD statement does notcause execution of the ON CLEAR TO ADD section.

You can use this statement to create a selected set based on data other than rows in atarget table. For example, you can use a loop, stored procedure, or C-hook to readdata from a file to build a selected set.


��

��

��

��

��

��

��

In this example, a selected set is created from data provided by a stored procedurenamed sp_companies( ). After all records have been added to the selected set, theform displays the first record of the set.

CLEAR TO ADD /* Clear the form to add a new record to the selected set */SET $co_key, $co_name TO sp_companies()EXECUTINGBEGIN

UPDATE CURRENT RECORD /* Add this record to the selected set */CLEAR TO ADD /* Prepare to add another record to the set */

ENDNEXT ACTION IS FIRST_RECORD

AFTER ADD, AFTER UPDATE, BEFORE ADD, BEFORE UPDATE, DELETECURRENT RECORD, UPDATE CURRENT RECORD“Add/Update/Delete Mode” in ��&��' ��

Syntax

Description

AffectedSections

Example

See Also


�

CLOSE PIPELINE

Output statement

��

pipe_name The ACCELL/SQL variable specified by the CREATE PIPELINEstatement.

The CLOSE PIPELINE statement closes the pipeline identified by the pipe_name.The ACCELL/SQL pipeline feature enables you to pass data from your application toan external data file or to another program.

Pipelines must be closed before the application ends to avoid loss of data. Thepipeline must already exist before it can be closed. To create a pipeline, use theCREATE PIPELINE statement.

This statement closes the pipeline identified by $pipe1. Before closing the pipeline,any remaining data is transmitted to the waiting file or process.

CLOSE PIPELINE $pipe1


CREATE PIPELINE, WRITE PIPELINE

Syntax

Arguments

Description

Example

AffectedSections

See Also


COMMIT WORK

Transaction statement

��

��&��&��



or



The COMMIT WORK statement terminates the current transaction and commitsdatabase changes made by the current transaction.

For INFORMIX SE and SYBASE SQL Server, the ACLTXMODE configuration variableis set to TRUE by default and ACCELL/SQL automatically begins and commitstransactions. When automatic transaction handling is enabled, a new transaction isbegun after COMMIT WORK is executed. If permitted by the RDBMS, all locks areretained, but all exclusive locks are downgraded to shared locks. If the RDBMS doesnot provide locking control, all locks are released.

However, if ACLTXMODE is set to FALSE, automatic transaction handling is disabled.When automatic transaction handling is disabled, the CHOOSE FIRST FORM orCHOOSE NEXT FORM transaction level specifications have no effect. Therefore,you must explicitly begin and commit transactions by using the BEGIN WORK andCOMMIT WORK statements.


Syntax

Arguments

Description


�

The ACLTXMODE configuration variable and the tx_mode$( ) system function haveno effect if you are using INFORMIX on a MODE ANSI database, or are usingINGRES, ORACLE, or Unify DataServer. These RDBMSs always automatically starttransactions.

If the AUTO_COMMIT form attribute is set to TRUE, ACCELL/Managerautomatically commits each transaction after every successful interactive databaseoperation.




COMMIT WORK

In this example, automatic transaction handling is first disabled, and then the currenttransaction, if any, is committed. A new transaction is then started to process andcommit an update operation.

tx_mode$(FALSE)BEGIN WORKUPDATE emp SET salary = salary * 1.1;IF (status$()=SS_NORM) THEN

COMMIT WORKELSE

ROLLBACK WORK/* There is no active transaction at this point. */

BEGIN WORK, CHOOSE FIRST FORM, CHOOSE NEXT FORM,ROLLBACK WORK, SLOCK, UNLOCK, XLOCK, tx_mode$( )

Example

See Also


�

CONTINUE


��

The CONTINUE statement immediately begins a new iteration of a FOR, REPEAT,SET/SELECT EXECUTING, or WHILE statement.

When executed within a FOR, REPEAT, or WHILE loop, the control expression isimmediately evaluated or reinitialized. If the expression is true, the next iteration ofthe loop is executed. If the control expression is false, the loop is terminated andexecution skips to the statement following the loop.

When executed within a SET/SELECT EXECUTING statement, the next record isretrieved and the statement block is executed again. If there is no next record, theloop is terminated.

The CONTINUE statement affects the current nested loop only. A CONTINUEstatement placed outside a FOR, REPEAT, SET/SELECT EXECUTING, or WHILEstatement results in an error.

This example checks the hobbies table for the selected employee and determineswhether the employee plays chess. If the employee’s hobby is not chess, theCONTINUE statement lets the report execution proceed.

SET $emp_id TO SELECT emp_id FROM employee WHERE emp_name = $nameEXECUTINGBEGIN

SET hobby TO SELECT hobby FROM hobbiesWHERE emp_id = $emp_id AND hobby = ’chess’

IF status$() <> 0 THENCONTINUE

WRITE PIPELINE $report $name...

END

Syntax

Description

Example


CONTINUE


BREAK, EXECUTING, FOR, REPEAT, SET, WHILE

AffectedSections

See Also


�

CREATE PIPELINE

Output statement

��

pipe_name A standard ACCELL/SQL variable to receive the file descriptor ofthe opened pipeline.

program_list A series of formatting program names, separated by commas. Data ispiped from program to program in the order that programs are listedin program_list. If you use literal program names rather thanvariables, each program name, along with any arguments, must beenclosed within a pair of apostrophes (’).

string_expressionThe directory path and file name of the data file to receive outputfrom the last process in the pipeline. The expression can be either astring constant or string variable.

The CREATE PIPELINE statement creates a pipeline. A pipeline sends informationout of the application to external formatting programs. When ACCELL/Managerexecutes the statement, it creates an operating system pipeline and stores thepipeline’s file descriptor in the variable pipe_name.

To avoid loss of data, do not change the value of the pipeline variable until after youhave closed the pipeline with the CLOSE PIPELINE statement.

When a WRITE PIPELINE statement is executed, ACCELL/Manager transmits datathrough the pipeline to the programs in program_list. The programs in program_listrepresent the operating system pipe. That is, the output of the application goes to thefirst program. The output of the first program becomes the input to the secondprogram, and so on.

Any command line arguments needed by a program in program_list must be part ofthe same string as the program name.

Syntax

Arguments

Description


CREATE PIPELINE

With the OUTPUT clause, ACCELL/Manager can direct the data from the lastprogram in the pipeline to a data file. The name of this data file is identified bystring_expression.

You can use the ACCELL/SQL system function status$( ) to determine whethercreation of the pipeline was successful.


This example creates a pipeline called pipe_one. This pipeline sends data from theapplication to the report generator RPT and then to the line printer, lpr. The RPT callin the program_list includes two RPT arguments. RPT receives its formattingcommands from the script file and the report information from the standard input(indicated by the minus sign).

CREATE PIPELINE $pipe_one ’RPT script –’,’lpr’

CLOSE PIPELINE, WRITE PIPELINE, status$( )

AffectedSections

Example

See Also


�

CREATE SCHEMA


��'��(��"��""��(��$��)



DDL_statementsAny of the DDL statements allowed by the RDBMS within aCREATE SCHEMA command. If more than one statement is listed,the statement list must be enclosed by a pair of parentheses.

The CREATE SCHEMA statement defines a database schema.




This statement creates a database schema named manufacturing.

CREATE SCHEMA manufacturing (GRANT SELECT ON SCHEMA manufacturing TO PUBLICGRAND ACCESS ON manufacturing TO me, you);

DROP SCHEMA��!"#$��%�� Documentation provided by the RDBMS vendor

Syntax

Support

Arguments

Description

AffectedSections

Example

See Also


CREATE TABLE


��*��(��+��"� �� #�)�)�)�$�)



table_name The name of the database table to be created.

column_name The name of a column to be created.

data_type The data type and length of the column.

The CREATE TABLE statement defines a new table.


ACCELL/SQL variables can be used as parameters within this statement but must beprefixed by a dollar sign ($). When using ACCELL/SQL parameters, do not enclosethis statement within a BEGIN_SQL and END_SQL statement block.


This statement creates a names table containing two columns: last_name andfirst_name.

CREATE TABLE names (last_name CHAR (60),first_name CHAR (60));

DROP TABLE��!"#$��%�� Documentation provided by the RDBMS vendor

Syntax

Support

Arguments

Description

AffectedSections

Example

See Also


�

CREATE TIMER EVENT


��

��

�

��

variable The name of a variable where the event ID is to be stored.

float_expr Expression that specifies the minimum number of seconds that musttranspire before the timer handler function is executed.

function_name The name of a global TIMER function declared by an EXTERNstatement.

The CREATE TIMER EVENT statement installs a request for a timer event anddefines a timer function to be called when the timer event occurs. If the timerfunction does not exist, a runtime error occurs.

When a timer event is installed, the variable is assigned an internal event ID for thisevent. The event ID value must be used in later references to the timer event.

The value specified in float_expr is a number of seconds and can be a fractionalvalue, for example, 3.5 seconds.

ACCELL/SQL services a timer only when the user has stopped on a field for input. Ifthe specified number of seconds has already expired when the user stops on a fieldfor input, the timer event is executed. Likewise, the timer event will be executed ifthe number of seconds expires when the user is editing a field. Timer events can bedeinstalled to prevent execution of the handler function.

Each timer event is executed only once per installation. To execute the same timerevent function again, the timer event request must be reinstalled.

Syntax

Arguments

Description


CREATE TIMER EVENT

You must define a timer event handler function as a global FUNCTION, using thefollowing syntax:

TIMER FUNCTION function_name(event_ID) function body

You must declare a timer event handler function before it can be referenced in theCREATE TIMER EVENT statement. The timer event handler function must bedeclared in the EXTERN statement, using the following syntax:

EXTERN ACCELL TIMER FUNCTION function_name(event_ID)

A timer event handler function requires one nonresult parameter. You cannot use atimer event handler function to return a value, and statements such as SET $a totimefunc(3) are invalid.

WarningTimer events are asynchronous. If a timer is serviced while a field is being editedby the user, the state under character mode is different from the state under agraphical user interface. Under a graphical user interface the widget’s value ischanged by the timer. In character mode the value will appear to be changed by thetimer, but when the user moves the cursor to the next field, the value will reflect thechange made by the user.

The following timer function definition displays a message to the user.

TIMER FUNCTION myfunc(id)BEGIN

DISPLAY ’Please enter data.’ FOR FYI_MESSAGE WAIT;

END;

The function is declared and used in a form script on the description field and isdeleted when the user exits the field:

EXTERN ACCELL TIMER FUNCTION myfunc(id)

FIELD descriptionBEFORE FIELD

CREATE TIMER EVENT $tid IN 10 SECONDS USING TIMER HANDLER myfunc...AFTER FIELD

DELETE TIMER EVENT $tid

Example


�

CREATE TIMER EVENT

The following function definition installs itself and recursively displays its event IDafter 10 or more seconds:

TIMER FUNCTION timerfunc(id)BEGINDISPLAY $id FOR FYI MESSAGE WAITCREATE TIMER EVENT $timer_id IN 10 SECONDS USING TIMER HANDLER timerfuncEND

The following statement installs a timer event so that the timer event function will becalled with the event ID returned in $a after 2.5 seconds. Meanwhile, statementsbeyond the CREATE TIMER EVENT statement can be executed.

CREATE TIMER EVENT $a IN 2.5 SECONDS USING TIMER HANDLER functime

DELETE TIMER EVENT, EXTERN, FUNCTIONCH_TIMER_CHK in �� !��

See Also


CREATE VIEW


��,��*��+��"� ��$��,��)

view_name The name to be assigned to the view.

column_name_listA list of view column names.

SELECT_statementA SELECT statement that specifies the columns of base tables fromwhich the view can be derived.

The CREATE VIEW statement defines a database view.




This statement creates a view named salary.

CREATE VIEW salary (income, dept) ASSELECT sal+com, dept FROM emp;

DROP VIEW��!"#$��%�� Documentation provided by the RDBMS vendor

Syntax

Arguments

Description

AffectedSections

Example

See Also


�

DEFINE COMMAND

Command execution section Master application and standard form scriptsUser-interface dependent

��

��

��

��

��

��

� ��

The BUTTON clause is supported for graphical user interfaces only.

command_nameName of a developer-defined user command. To avoid potentialconflicts with reserved words, you can enclose command nameswithin a pair of quotation marks (”).

ACTION Activates the command in both find mode and add/update/deletemode. The ACTION attribute cannot be used in combination with theAUD_ACTION and FIND_ACTION attributes. Assigning a promptstring to ACTION overrides the settings of both the AUD_ACTIONand FIND_ACTION attributes.

AUD_ACTION Activates the command in add/update/delete mode only. TheAUD_ACTION and FIND_ACTION attributes can be used incombination.

Syntax

Support

Arguments


DEFINE COMMAND

FIND_ACTION Activates the command in find mode only. The AUD_ACTION andFIND_ACTION attributes can be used in combination.

enable_string Action specifier assigned to the action attribute. The enable_stringdetermines the response of ACCELL/Manager when the user pressesthe function key. The enable_string can be either of two values:

’ENABLED’ (Default) The function key is enabled and acommand label is displayed in the function keyprompt system field.

’DISABLED’ No label is displayed in the prompt area; a bell(beep) character is sent to the terminal if the userpresses the key. No event sections or statements areexecuted. If a function key action is set toDISABLED, no function key prompt is displayed,regardless of the label attribute settings.

By setting the AUD_ACTION attribute toDISABLED, you disable the function key inadd/update/delete mode. By setting theFIND_ACTION attribute to DISABLED, you disablethe function key in find mode.

You can set the function key action to DISABLED inboth form modes by setting the ACTION attribute toDISABLED. Assigning the DISABLED value toACTION overrides the settings of both theAUD_ACTION and FIND_ACTION attributes.

LABEL Defines the function key prompt for both find mode andadd/update/delete mode. The LABEL attribute cannot be used incombination with the AUD_LABEL and FIND_LABEL attributes.Assigning a prompt string to LABEL overrides the settings of theAUD_LABEL and FIND_LABEL attributes.

If a function key action is set to DISABLED, no function key promptis displayed, regardless of the LABEL setting.


�

DEFINE COMMAND

AUD_LABEL Defines the prompt that appears when the form is inadd/update/delete mode. The AUD_LABEL and FIND_LABELattributes can be used alone or in combination.

If a function key action is set to DISABLED, no function key promptis displayed, regardless of the AUD_LABEL setting

FIND_LABEL Defines the prompt that appears when the form is in find mode. TheAUD_LABEL and FIND_LABEL attributes can be used alone or incombination.

If a function key action is set to DISABLED, no function key promptis displayed, regardless of the FIND_LABEL setting

string_expr String expression to be used as the label for the command. The labelappears in the function key prompt system field. If not explicitlyspecified, the default label is the name of the command as specifiedin the resource file.

’None<Key>Fnn’

Fnn is a function key name, such as F4 or F11. The key expression iscase sensitive and must be entered exactly. For example, to specifyfunction key �� , you use the following string:

’None<Key>F5’

modifier<Key>keysym(Graphical user interfaces only) Specifies a key event.

modifier specifies an event modifier key, for example:

Alt Mod1 Button1 HyperCtrl Mod2 Button2 SuperLock Mod3 Button3 NoneMeta Mod4 Button4 AnyShift Mod5 Button5

Event modifier key names are dependent upon the syntax required byyour graphical user interface.


DEFINE COMMAND

keysym is an X11 keysym name, as found in the keysymdef.h file.By default, the key sequence overwrites similar existing keysequences for the command.

position (Graphical user interfaces only) Specifies a set of coordinates:

row, column

where row is the row number and column is the column number,starting from (0,0). The position values are in parentheses.

statements Any valid �� statements.

The DEFINE COMMAND section contains the statements that define the task to beperformed by a function key for a developer-defined command. This section can alsobe used to disable a function key or to set the function key prompt.

By default, developer-defined commands apply to the current form only. To controlthe scope of commands, use the CMDSCOPE configuration variable.

Function keys and commands can differ between find mode and add/update/deletemode. However, at any one time, a function key can be assigned to only onecommand and a command can be assigned to only one function key.

� !"#$%!&��'� ��(� )!%�'

For graphical user interfaces only, you can define command buttons and key events.The order of commands on the User menu is determined by the order in which thecommand definitions appear in the form script. To ensure that commands occur in thedesired order, place all DEFINE COMMAND statements together near the top of theform script file.

Description


�

DEFINE COMMAND

When a command action is ’ENABLED’, the command label is displayed in asensitive button on the User pull-down menu. Users can execute the command eitherby selecting the command button or by pressing the command key sequence. When acommand action is ’DISABLED’, the command label is displayed as an insensitive(stippled or gray-shaded) button on the User pull-down menu. Users cannot executethe command.

If no command label is specified in the DEFINE COMMAND section, the defaultlabel is taken from the resource file. If the command label is not specified in theDEFINE COMMAND section or in the resource file, the default label is the name ofthe command.

While commands can be enabled or disabled both at creation and throughACCELL/4GL, command activators such as key sequences and button locations canbe specified only when the button is created. As a result, a command can be accessedby using one or more of the following methods, depending on the commandactivators defined for the command:

a key sequence

a button on a user menu

a button within a specific form

A command can also be created without initially associating it with any of thepreceding access methods. In such a case, the command key sequence can beactivated at a later time by using the ACCELL/4GL SET COMMAND statement.However, the button cannot be created at a later time by using SET COMMAND,because the SET COMMAND statement does not include a BUTTON clause.

A command event modifier can specify combinations or limitations, for example:

None No modifiers are allowed.Any Any or no modifier is allowed.Mod1 Mod2 Both Mod1 and Mod2 are required; other modifiers are also

allowed.!Mod1 Mod2 Only Mod1 or Mod2 are allowed; other modifiers are prohibited.Mod1 ~Mod2 Mod1 is required; all other modifiers except Mod2 are allowed.

A modifier is optional. For complete information about modifiers, see the X11translation table syntax specified for your graphical user interface.

Command Actions

CommandLabels

CommandAccess

CommandKeys


DEFINE COMMAND

Keys can be specified by the keysym name or value specified in the keysymdef.hfile. Some translations may require the keysym value if symbolic names are notproperly interpreted. The keysym name is case sensitive and must be entered exactlyas specified in the translation table (remove the XK_ prefix).

The BUTTON clause enables you to control whether the command button is to becreated on the User pull-down menu, somewhere on the form, or not at all.

LOCATION IS ON USERMENU Specifies that the command button is to be created on the Userpull-down menu. This is the default.

LOCATION IS NOT ON USERMENU Specifies that the command button is not to be created on the Userpull-down menu nor anywhere on the form. However, if thecommand is enabled, users can execute the command by pressing thekey sequences defined for the command.

AT (position) Specifies that the command button is to be created on the form in thespecified row and column position. Make sure that you do not place abutton so that it is in the same position as a screen field, because thescreen field will overlay the button.

When a button is created on the form, instead of on the Userpull-down menu, the button is deactivated when another form ismade current. (A deactivated button usually appears stippled orgrayed so that it is less readable than activated buttons.)

At runtime, if the button position is outside the bounds of a form, anerror message is displayed, and the button is not created.Nonetheless, if key sequences are defined for the command but thecommand button does not exist, users can execute the command bypressing the key sequence.

You can define button resources in resource files (AccellOL or AccellM). Thisenables you to set default font, color, height, and width for a developer-definedcommand button. Button height and width are specified in number of characters.

PositioningButtons


�

DEFINE COMMAND

The BUTTON clause has no effect in character mode applications.

All ACCELL/4GL statements are valid in this section.

The following example defines a command named mail that by default is enabled.The command is invoked when the user presses the �� key. The label that appears inthe function key prompt field is F7–Get Mail.

DEFINE COMMAND mailACTION IS ’ENABLED’,LABEL IS ’F7–Get Mail’,KEYS ARE ’None<Key>F7’,system$(’mail’)

...;

The following example defines a command named mail that by default is enabled.The example also defines a command key sequence and a label, which is to appear onthe User command pull-down menu. Users can execute the command either bypressing �� M or by selecting the Check Mail button on the User commandpull-down menu.

DEFINE COMMAND mailACTION IS ’ENABLED’,LABEL IS ’Check Mail’,KEYS ARE ’Ctrl<Key>M’,BUTTON LOCATION IS ON USERMENUsystem$(’mail’)

� �

ACTION, AUD_ACTION, AUD_LABEL, FIND_ACTION, FIND_LABEL, LABELattributesCLEAR COMMAND QUEUE, QUEUE COMMAND, SET COMMANDlast_command$( ), last_command_name$( )CMDSCOPE in �� !��"��#��$%��&��'��"��(��“Defining User Commands” in ��)��*��

AffectedStatements

Example

GraphicalUser

Interface

See Also


DEINSTALL

Function statement

�� '��

handler_id Specifies the error-handler function ID that is to be deinstalled.

The DEINSTALL statement deinstalls one or all handler functions.

This statement is valid in all ACCELL/4GL event sections.

This example installs and deinstalls an error-handler function identified as $genid;

BEFORE FORMINSTALL DBMS_ERROR HANDLER gen_handler

FOR EVENTS EXCEPT SS_DUPK, SS_NORECidentified BY $genid

. . .AFTER FORM

DEINSTALL $genid

This statement deinstalls all error-handler functions:

DEINSTALL ALL DBMS_ERROR

EXTERN, FUNCTION, INSTALL, status$( )“Creating Functions” in ��)��*��

Syntax

Arguments

Description

AffectedSections

Example

See Also


�

DELETE

SQL DML statement RDBMS dependent

�� '��*��+,��

This statement must conform to the syntax required by the RDBMS. In addition, seethe restrictions for INFORMIX and ORACLE described below.


table_name The name of a database table containing the rows to be deleted.

logical_expressionAn RDBMS logical expression that evaluates to TRUE or FALSE.The expression is evaluated to determine which rows in the databasetable to delete.

The DELETE statement initiates a noninteractive delete operation to delete a row orrows from a specified database table, table_name. The set of rows to be deleted isdetermined by the WHERE clause. DELETE deletes all rows that satisfy thelogical_expression in the WHERE clause. This logical_expression must include a teston at least one column name from the table table_name.



Syntax

Support

Arguments

Description


DELETE

An exclusive lock is placed on each deleted row. If DELETE cannot obtain a lock onthe row or if any other error occurs, the delete operation fails and the statementterminates.

If the WHERE clause is omitted, DELETE attempts to delete all rows in the specifiedtable. These rows are deleted if DELETE does not encounter an error during thedelete operation.

You can use the status$( ) system function to test the success of a DELETEstatement. If the user does not have delete privilege, the status$( ) function returns astatus code of SS_WRACS after a delete operation. If the record to be deleted is notfound, status$( ) returns SS_NOREC.

WarningUsing a noninteractive database statement to delete rows that have records inthe form’s selected set does not delete the selected set records. The selected setrecords remain unaffected by the delete operation although their associated rows havebeen deleted.

��-

The WHERE clause cannot include a column having the TEXT or BYTE data type.

��

The WHERE clause cannot include a column having the LONG or LONG RAW datatype.



�

DELETE

This DELETE statement deletes all rows in the table stock where the stock numbersare less than 1000. If the noninteractive delete operation fails, the user is notified andthe current transaction is rolled back.

SET limit TO 1000DELETE stock WHERE st_number < $limit;IF ( status$() <> SS_NORM ) THEN

BEGINROLLBACK WORKDISPLAY ’Noninteractive delete failed; aborting tx’

FOR FYI_MESSAGE WAITEND

DELETE CURRENT RECORD, DELETE SELECTED ROW, GRANT, INSERT,SELECT, UPDATE, UPDATE CURRENT RECORD��#$+,��(��Documentation provided by the RDBMS vendor

Example

See Also


DELETE CURRENT RECORD

Delete statement

��

The DELETE CURRENT RECORD statement simulates the ��

command. It initiates an interactive delete operation to delete the target table rowassociated with the form’s current record. After the current record is deleted, anotherrecord in the selected set becomes current.

DELETE CURRENT RECORD does not cause the execution of any delete sections(BEFORE DELETE or AFTER DELETE).

This statement requests an exclusive lock on the current record’s target table row. Ifthis exclusive lock request is successful, DELETE CURRENT RECORD performs theinteractive delete operation. You can use the status$( ) system function to test thesuccess of a DELETE CURRENT RECORD statement.

This statement cannot be used within a FUNCTION section.

This statement verifies that the user intends to delete the current record. If the userresponds yes, the delete operation is performed.

IF (yesno$(’Are you sure you want to delete this record?’; –1))THEN DELETE CURRENT RECORD

AFTER DELETE, CLEAR TO ADD, DELETE, DELETE SELECTED ROW, INSERT,UPDATE, UPDATE CURRENT RECORD

Syntax

Description

AffectedSections

Example

See Also


�

DELETE SELECTED ROW

ACCELL/4GL delete statement RDBMS dependent

�� +.�

INFORMIX Supported.

INGRES Supported.

ORACLE Supported.

SYBASE SQLServer

The DELETE SELECTED ROW statement is notsupported for SYBASE SQL Server.

Unify DataServer Supported.

The DELETE SELECTED ROW statement initiates a noninteractive delete operationto delete a row retrieved by a SELECT statement. The statement must be terminatedby a semicolon (;).

This statement can be used only within an EXECUTING block to delete a selectedrow. If the EXECUTING block is nested within other EXECUTING blocks, thedeleted row is the row associated with the innermost block.

This statement can be used only when the table of the associated SELECT statementis updatable, as determined by the RDBMS. The SELECT statement can contain nomore than one table in the FROM clause and cannot contain a GROUP BY, ORDERBY, or HAVING clause.

If DELETE SELECTED ROW cannot lock the selected row or if any other erroroccurs, the delete operation fails.

The DELETE SELECTED ROW statement does not cause execution of the BEFOREDELETE and AFTER DELETE statements.

Syntax

Support

Description


DELETE SELECTED ROW

Use the status$( ) system function to test the success of a DELETE SELECTEDROW statement. If the user does not have delete privilege, the status$( ) functionreturns a status code of SS_WRACS after a delete operation.

WarningUsing the DELETE SELECTED ROW statement to delete rows that are in theform’s selected set does not delete the selected set records. The selected setrecords remain unaffected by the delete operation although their associated rows havebeen deleted.


This portion of a form script uses the DELETE SELECTED ROW statement to deleteall records in the employee table where the emp_last_name field contains“Harrigan”.

SET emp_last, emp_first toSELECT emp_last_name, emp_first_name FROM employeeEXECUTING

BEGINIF (emp_last = ’Harrigan’) THEN

BEGINDISPLAY ’Deleted employee’ + emp_first + ’ ’ + emp_last

FOR FYI_MESSAGE WAITENDDELETE SELECTED ROW;

END

AFTER DELETE, DELETE, DELETE CURRENT RECORD, EXECUTING, ONFIND, SELECT, UPDATE CURRENT RECORD, UPDATE, UPDATE SELECTEDROWstatus$( )��#$+,��(��

AffectedSections

Example

See Also


�

DELETE TIMER EVENT


�� /�� %�� /��

variable The name of the variable where the event ID is stored, as specified inthe CREATE TIMER EVENT statement.

The DELETE TIMER EVENT command removes a timer event request from internalqueues, thus preventing the timer event from being executed. The value of variable isunchanged.

The DELETE ALL TIMER EVENTS command removes all installed timer eventsfrom the internal queues.

This statement deletes a timer event identified by $timer_id.

DELETE TIMER EVENT $timer_id

CREATE TIMER EVENT, EXTERN

Syntax

Arguments

Description

Example

See Also


DISABLE ZOOM TO

Form sequence control statement

��0� ��

form_name The name of the zoom form. This name can either be the literal formname (without quotes) or a string expression.

The DISABLE ZOOM TO statement disables a zoom-enabled form field. When thefield is not zoom enabled, the user cannot access the zoom form. The zoom form isdisabled when the form is in either form mode.

Disabling an already disabled zoom does not produce an error.

This statement cannot be used in the FUNCTION section.

This sample disables the zoom form fsalesrep from the current form field, sales.

FIELD salesBEFORE FIELD

DISABLE ZOOM TO fsalesrep

ENABLE ZOOM, ZOOM RETURN VALUES

Syntax

Arguments

Description

AffectedSections

Example

See Also


�

DISPLAY

Output statement

��1��

��

��+��

��1��2��

��

��,

��

��

expression The ACCELL/SQL expression to be displayed. This expression can bea string, a numeric constant, a numeric expression or any other validACCELL/SQL expression.

form_field The name of the form field where the value of expression is to bedisplayed.

format_expressionAn ACCELL/SQL format template that specifies a format fordisplaying the expression.

string_expressionA string variable set to any of the values LEFT, RIGHT, orCENTERED.

The DISPLAY statement displays an expression on the screen. You can specify thatexpressions be displayed in form fields or in the fyi_message system informationfield.

Identifying the Value to Be Displayed

You list the value to be displayed after the keyword DISPLAY. This value is anexpression of any ACCELL/SQL type except BINARY. The form field name is used toposition the display value. The expression’s data type need not match the data type ofthe form field where you display the expression.

Syntax

Arguments

Description


DISPLAY

Specifying the Display Field

The FOR clause specifies where the value is to be displayed. If the FOR keyword isfollowed by the name of a form field, the value is displayed in that field.

If expression is omitted and the FOR clause includes FYI_MESSAGE,ACCELL/Manager displays the current value of the current form field in thefyi_message system information field of the screen form.

If the FOR clause is omitted, expression is displayed in the current form field. Ifexpression is omitted and the FOR clause includes a form field, ACCELL/Managerdisplays the current value of form_field. This form_field is the position where theexpression is displayed. None of the field attributes, such as DISPLAY_FORMAT,affect the expression.

If the display value is omitted, ACCELL/SQL displays the current value of the fieldlisted in the FOR clause.

The expression message can be any string expression. By using the concatenationoperator (+), you can create a longer string by joining two or more smaller strings.

If you omit the expression from this statement but include the FOR FYI_MESSAGEclause, ACCELL/Manager displays the current value of the current field in thefyi_message system information field. The current field is the field that the cursor ispositioned on when the DISPLAY statement is executed. The current value of thisfield is the value of the field’s associated field variable.

If you include the WAIT clause in the DISPLAY statement, ACCELL/Manager pausesexecution and waits for the user to press ��. After receiving ��,ACCELL/Manager resumes execution. Without the WAIT clause, the expression canbe overwritten by a form field message when ACCELL/Manager returns to the formfield. If you omit the WAIT clause, the form field message is displayed and executioncontinues.

If the fyi_message system information field is not defined, ACCELL/Manager ignoresthe DISPLAY FOR FYI_MESSAGE statement. However, if you include the WAITclause on DISPLAY FOR FYI_MESSAGE and don’t have an fyi_message systeminformation field defined, ACCELL/Manager will appear to “hang” because the WAITclause tells it to wait for the user to press ��. In this case, the user must press�� to continue execution.


�

DISPLAY

Formatting the Value

You can include two types of custom display formatting in the DISPLAY statement:

field justification with the DISPLAY_JUSTIFY clause

a format specified with the USING clause

The DISPLAY_JUSTIFY clause specifies how the display value is justified in theform field. By default, ACCELL/Manager displays values of all data types as leftjustified.

To justify a field, include the DISPLAY_JUSTIFY clause followed by the keyword forthe type of field justification needed: LEFT, RIGHT, or CENTERED.

You can alternatively list the justification type as a string expression instead of as oneof the keywords.

The format_expression in the USING clause is a format template that determines howAMOUNT, NUMERIC, FLOAT, and STRING values are displayed in the fieldwindow. A display format in the USING clause overrides the setting of the field’sDISPLAY_FORMAT attribute. If the USING clause is omitted, ACCELL/SQL uses theformats defined by your langcap variables. For information about how to create aformat template, see ��-��.

When a FOR clause is included, the DISPLAY statement is valid in all ACCELL/4GLevent sections.

If a FOR clause is omitted, this statement is not valid in the FUNCTION section.

AffectedSections


DISPLAY

The following DISPLAY statement uses the system function current_date$( ) todisplay the data in the ld_next_date field on the fleads form.

DISPLAY current_date$() FOR fleads:ld_next_date

The next DISPLAY statement displays the status value in the fyi_message systeminformation field. This status message consists of the string “status is ” followed bythe status$( ) return value that has been converted to a string.

DISPLAY ’status is ’ + val_to_str$( status$() )FOR FYI_MESSAGE WAIT

DISPLAY FORMAT, DISPLAY HELP, DISPLAY TRIM, ERASE HELP, ERASE TRIM“Controlling Information Display” in ��)��*��-��

Example

See Also


�

DISPLAY HELP

Screen control statement

��1��,��1��'��'��'�%�� +��

help_form_nameThe literal form name or a defined, non-null string expression.

help_archive The name of a help archive.

position The row and column coordinates of the upper left corner of thedisplayed help form. Any numeric expression can be used for rowand column numbers.

The DISPLAY HELP statement enables you to share help forms or error messagescreens among forms and fields of an application or among several applications.

If you omit the FOR help_form_name clause, ACCELL/SQL displays the help formnamed for the current field in the HELP_FORM_NAME field attribute. With theFOR help_form_name clause, ACCELL/SQL displays the specified help form.

The optional FROM clause enables you to display a help form from a help archiveshared among applications. If you omit the FROM clause as well as the FOR clause,ACCELL/SQL uses the current field’s help archive and form.

The AT clause specifies the location of the upper left corner of the help form. Aposition is indicated by a set of coordinates:

[@](row, column)

where row is the row number and column is the column number, starting from 0,0.The optional at symbol (@) preceding the position indicates absolute coordinatesrather than coordinates relative to the calling form’s origin. If the AT clause isomitted, ACCELL/Manager uses the location of the form’s most recent occurrence forthe form position.

Syntax

Arguments

Description


DISPLAY HELP

The WAIT clause displays the message “Press RETURN to continue” in thefyi_message system information field and causes the application to pause until theuser presses ��.

If you use the WAIT clause or deactivate the form you do not need to use the ERASEHELP statement after using DISPLAY HELP. Otherwise, the ERASE HELP statementis needed after each DISPLAY HELP statement.


This statement displays a help form if the user enters a date that is earlier than thecurrent date. The form displays until the user presses ��.

IF $date < current_date$() THENDISPLAY HELP FOR date_error_01 FROM app_errors AT (10,10) WAIT ;

DISPLAY, DISPLAY TRIM, ERASE HELP, ERASE TRIM

AffectedSections

Example

See Also


�

DISPLAY TRIM


��1�� +��

form_name The name of form whose trim is being displayed. This name caneither be the literal form name (without quotation marks) or a stringexpression. The form_name cannot be a help form name.

position The row and column coordinates of the upper left corner of thedisplayed trim. Any numeric expression can be used for row andcolumn numbers.

The DISPLAY TRIM statement creates and displays a copy of a form’s trim. Eachexecution of the statement creates a new copy of the trim. The statement produces acopy of the trim; it does not display an actual form. The form copy cannot acceptinput as the actual form can.

The FOR clause specifies the form whose trim is to be displayed. If you omit theFOR clause, the statement displays the calling form’s trim.

The AT clause determines the location of the upper left corner of the form trim. Aposition is indicated by a set of coordinates:

[@]( row, column )


Syntax

Arguments

Description


DISPLAY TRIM

If there is not is not enough room on the screen to display form trim at the specifiedposition, a runtime error occurs.

The WAIT clause displays the following message in the fyi_message systeminformation field:

Press RETURN to continue

The application then pauses until the user presses the �� key. When the userpresses ��, the form trim is automatically erased.

DISPLAY TRIM statements can alter a part of the screen not within the form window.The window created for the new trim is controlled by the current form. If the windowis not erased by an appropriate ERASE TRIM statement, it will be automaticallyerased when the user exits the current form.


This first example statement displays the trim for the form fitems at the most recentoccurrence of the fitems form.

DISPLAY TRIM FOR fitems

This second statement displays a custom error window named err_form. This errorform is displayed beginning at row 3, column 10. The WAIT clause tellsACCELL/Manager to wait for the user to press �� before erasing the trim tocontinue. Notice that the form coordinates are absolute coordinates.

DISPLAY TRIM FOR err_form AT @(3,10) WAIT

DISPLAY, DISPLAY HELP, ERASE HELP, ERASE TRIM

AffectedSections

Example

See Also


�

DROP SCHEMA


��1��,��'��

This statement must conform to the syntax required by the RDBMS.

schema_name The name of a database schema.

The DROP SCHEMA statement drops (destroys) a schema definition.


If you use ACCELL/SQL variables as parameters in the DROP TABLE statement,prefix each variable name with a dollar sign ($).

Do not enclose this statement within a BEGIN_SQL and END_SQL statement block.


This DROP SCHEMA statement destroys the schema named accounting.

DROP SCHEMA accounting;

ALTER SCHEMA, CREATE SCHEMA��#$+,��(��Documentation provided by the RDBMS vendor

Syntax

Support

Arguments

Description

AffectedSections

Example

See Also


DROP TABLE


��1� ��'��*��.��



table_name The name of the table that is to be dropped.

The DROP TABLE statement drops (destroys) a table definition.




This DROP TABLE statement destroys the employee table.

DROP TABLE employee;

ALTER TABLE, CREATE TABLE��#$+,��(��Documentation provided by the RDBMS vendor

Syntax

Support

Arguments

Description

AffectedSections

Example

See Also


�

DROP VIEW


��1�/��+�%�/��


view_name The name to the view that is to be dropped.

The DROP VIEW statement drops (destroys) a view definition.


ACCELL/SQL variables can be used as parameters within this statement but must beprefixed by a dollar sign ($). When using ACCELL/SQL parameters, do not enclosethis statement within a BEGIN_SQL and END_SQL statement block.


This DROP TABLE statement destroys the salary view.

DROP VIEW salary;

CREATE VIEW��#$+,��(��Documentation provided by the RDBMS vendor

Syntax

Support

Arguments

Description

AffectedSections

Example

See Also


ENABLE ZOOM


��0

��

��

��

�� 1��

��

�� /�� %��03�%��13� � � �3�%��

form_name The name of the zoom form. This name can either be the literal formname or a string expression.

position The row and column coordinates of the upper left corner of the form.Any numeric expression can be used for row and column numbers.

numeric_expressionAny expression that evaluates to a NUMERIC value. This numericexpression determines the number of times that the repeating areaappears on the form at runtime.

var The name of a form field where the value is to be inserted.

The ENABLE ZOOM statement specifies a zoom form for the current form field. Azoom form is a special form that provides the user with a “window” into another partof the database. The user can look up and retrieve data without leaving the context ofthe current form.

When you enable the zoom capability on a form field, the form field is said to bezoom enabled.

Syntax

Arguments

Description


�

ENABLE ZOOM

When a field is zoom enabled, it remains enabled after execution of a clear-to-findoperation.

To enable the zoom capability, use the ENABLE ZOOM statement within the INITFIELD or BEFORE FIELD sections of the field that is to be zoom enabled. IncludingENABLE ZOOM in INIT FIELD zoom-enables the form field in both find andadd/update/delete form modes. Including ENABLE ZOOM in BEFORE FIELDzoom-enables the form field only in add/update/delete form mode because BEFOREFIELD is not executed in find mode.

The consistency level clause determines the zoom form’s consistency level. The threeconsistency level values are: RECORD_CONSISTENCY, SET_CONSISTENCY, andNO_CONSISTENCY. If the consistency level is omitted, the zoom form is executed atthe same consistency level as the calling form.

The AT clause determines the location of the upper left corner of the form trim. Aposition is indicated by a set of coordinates:

[@]( row, column )

where row is the row number and column is the column number, starting from 0,0.The optional at symbol (@) preceding the position indicates absolute coordinatesrather than coordinates relative to the calling form’s origin. If the AT clause isomitted, the zoom form has the form origin defined within ACCELL/Generator.

An error occurs if there is not enough room for the form on the screen.

The REPEATED clause governs the number of occurrences for a multi-occurrencezoom form. By default, ACCELL/Manager uses the number of occurrences defined forthe form on the Form Definition form. On a single-occurrence zoom form,ACCELL/Manager simply ignores the request.

The RETURN KEY clause lets the user bring primary key values or serial field valuesfrom the zoom form back to the calling form. To bring back a key value, the userpresses �� from the zoom form when the record having the desiredkey value is current.


ENABLE ZOOM

The RETURN VALUES clause lets the user bring nonkey values from the zoom formback to the calling form. To bring back a value, the user presses ��

from the zoom form when the record having the desired value is current.

If the RETURN VALUES clause includes the INTO keyword, the number of variablesspecified must match the number of fields specified in the ZOOM RETURN VALUESstatement.

If the RETURN VALUES clause does not include the INTO keyword, the returnedvalues go first into the field zoomed from and then into the next sequential fields, upto the number of values returned.

Field data types must match. The variables you are returning values from must havethe same data types as the corresponding variables into which you are assigningvalues.

To use the RETURN KEY clause, the zoom form must have a target table defined.

If a key consists of more than one column, there must be a form field on the originalform for each of the key values. The first key value is displayed in the zoom-enabledfield. Successive key fields are displayed in successive form fields in key field order.Key field order is specified in the database design.

If RETURN KEY is specified but there is no key to return, input resumes on thecalling form’s current field. Similarly, if the user presses �� from thezoom form, no key value is returned.

Enabling an already enabled zoom does not produce an error.

This statement can be used only in the following event sections:

AFTER FIELD INIT FIELDBEFORE FIELD ON FIELD

AffectedSections


�

ENABLE ZOOM

This example statement is in the BEFORE FIELD section of the fcompany form. Thestatement enables a zoom to the fsalesrep form from the co_sales_rep field. The usercan press �� on fsalesrep to return the sales representative key. Theco_sales_rep field is zoom-enabled only when the form is in add/update/delete modebecause the ENABLE ZOOM statement is in the BEFORE FIELD subsection.

FIELD co_sales_rep BEFORE FIELD

ENABLE ZOOM TO fsalesrep RETURN KEY

In the next example, the values returned from the Salesreps form are assigned to theSalesrep and Ext fields on the Company form.

ENABLE ZOOM RECORD_CONSISTENCY TO Salesreps RETURN VALUES INTO Salesrep, Ext ;

AUTO_ZOOMAFTER ZOOM, BEFORE FIELD, DISABLE ZOOM, INIT FIELD, ZOOM RETURNVALUES

Example

See Also


END_SQL

SQL block statement

��4�

The END_SQL statement marks the end of a SQL statement block. The SQLstatement block must begin with a BEGIN_SQL statement.

The database statements listed between the begin and end delimiters are sent directlyto the database for processing. ACCELL/SQL variables can be used within thestatement block, but the database cannot return values to the ACCELL/SQLapplication. The BEGIN_SQL and END_SQL statements themselves are not passed tothe database.

This statement is not required for SQL DML and DDL statements.


This example shows how the BEGIN_SQL and END_SQL statements are used toenclose an RDBMS-specific statement.

BEGIN SQLCREATE UNIQUE HASH INDEX

orders_hidx ON orders (ord_number)END SQL

BEGIN_SQL

Syntax

Description

AffectedSections

Example

See Also


�

ERASE HELP


��,��1��'��

help_form_nameThe literal form name or a defined, non-null string expression.

position The row and column coordinates of the upper left corner of thedisplayed help form. Any numeric expression can be used for rowand column numbers.

The ERASE HELP statement erases the last instance of a help form. If the help formhas been displayed several times on top of itself, ERASE HELP erases only the mostrecently created occurrence.

The FOR clause specifies the help form to be erased.

The AT clause specifies the location of the upper left corner of the help form to beerased. A position is indicated by a set of coordinates:

[@](row, column)

where row is the row number and column is the column number, starting from 0,0.The optional at symbol (@) preceding the position indicates absolute coordinatesrather than coordinates relative to the calling form’s origin.

If both the FOR clause and the AT clause are omitted, the statement erases the mostrecently displayed help form. If the FOR clause is included but the AT clause isomitted, the statement erases only a help form of the specified name. If the AT clauseis included but the FOR clause is omitted, the statement erases only a help formdisplayed at the specified coordinates.

Syntax

Arguments

Description


ERASE HELP


This statement erases the help form for the fitems form at the last place the helpinformation was displayed:

ERASE HELP FOR fitems

DISPLAY HELP, DISPLAY, DISPLAY TRIM, ERASE TRIM

AffectedSections

Example

See Also


�

ERASE TRIM


��

form_name The name of the form whose trim is being erased. This name caneither be the literal form name (without quotation marks) or a stringexpression. The form_name cannot be a help form name.

position The row and column coordinates of the upper left corner of thedisplayed trim. Any numeric expression can be used for row andcolumn numbers.

The ERASE TRIM statement erases the last instance of trim displayed at the specifiedposition. If trim has been displayed several times on top of itself, ERASE TRIMerases only the most recently created trim.

The FOR clause specifies the form whose trim is to be erased. If you omit the FORclause, the statement erases the most recent instance of the calling form’s trim at thelocation specified by the AT clause.

The AT clause determines the location of the upper left corner of the form trim. Aposition is indicated by:

[@]( row, column )


If the FOR and AT clauses are omitted, ERASE TRIM erases the last trim displayed.

Using the ERASE TRIM statement when there is no displayed trim is an error. Anerror message is also generated if the AT clause specifies a position at which there isno trim.

Syntax

Arguments

Description


ERASE TRIM


This statement erases the trim for the fitems form at the last place it was displayed.

ERASE TRIM FOR fitems

DISPLAY, DISPLAY HELP, DISPLAY TRIM, ERASE HELP

AffectedSections

Example

See Also


�

EXECUTING

Selection clause

�� %�� 2��-��

��

��

variable_list A list of one or more ACCELL/SQL variables separated by commas.Each variable is assigned the value of the corresponding column inthe SELECT statement.

SELECT_statementA SQL SELECT statement.

statement_blockAny valid SQL or ACCELL/SQL expression.

The EXECUTING clause is an optional component of a SQL SELECT statement.

The EXECUTING clause indicates that ACCELL/Manager is to select all matchingrows. For each selected row, ACCELL/Manager assigns the column values to thevariables in variable_list (if one exists) and then executes the statements instatement_block.

The variable_list and the column list in the SELECT statement must have the samenumber of elements. In addition, these lists are ordered: the value from the firstcolumn in the column list is assigned to the first variable in variable_list, the valuefrom the second column value to the second variable, and so on until the end of bothlists. For this reason, corresponding elements of the database column list andvariable_list must be type compatible.

Syntax

Arguments

Description


EXECUTING

If the SELECT statement includes a locking clause, locks are requested for allselected rows.

Without an EXECUTING clause, SELECT selects only the first row that matches thespecified search criteria and stops. Any other matching rows are not selected.

ACCELL/Manager assigns the specified column values to the variables in theSELECT variable list and then executes statements in the execution block once foreach selected row. Therefore, you can use the variables in the variable list within theexecution block.

The following table summarizes the combinations of the WHERE and EXECUTINGclauses and the rows selected by SELECT.

��

��-�� +,��

+,��-�� +,��

��

+,��! �� +,��

��

�-�� ! ��


The ROLLBACK WORK statement is invalid within the statement block.

AffectedSections

AffectedStatements


�

EXECUTING

This example shows a SELECT statement with an ORDER BY clause. The SELECTstatement sorts all rows in the employee table alphabetically by last name. If twoemployees have the same last name, the employees are sorted by first name. It thensends the last_name and salary values over the ACCELL/SQL pipeline report forformatting.

SET $last_name, $salary TOSELECT emp_last_name, emp_salaryFROM employeeORDER BY emp_last_name ASCENDING, emp_first_name ASCENDINGEXECUTING

BEGINWRITE PIPELINE $report, $last_name, $salary

END

The next SELECT statement selects all employees with a job code of “REP”. TheEXECUTING clause is executed once for each row selected. The effect is to displaythe values of the three variables for every employee with a job code of “REP”. Notethat none of the selected rows are locked, because the locking clause has beenomitted.

SET s_emp_first, s_emp_last, s_emp_ext TO SELECT emp_first_name, emp_last_name, emp_ext FROM employee WHERE emp_job_code = ’REP’ EXECUTING

BEGIN DISPLAY s_emp_first + s_emp_last + s_emp_ext WAIT

END

BREAK, CONTINUE, DELETE SELECTED ROW, INSERT, SELECT, SET, SLOCK,UPDATE SELECTED ROW, XLOCK

Example

See Also


EXIT


�-�

The EXIT statement ends execution of the application. This statement simulates theACCELL/Manager �� command.

This statement can be used in all ACCELL/4GL event sections and functions.

This EXIT statement exits the application when an error occurs.

IF (status$() <> SS_NORM) THENBEGINDISPLAY ’Database is unavailable at this time. Try again later.’

FOR FYI_MESSAGE WAITEXITEND

AFTER APPLICATION, ON EXIT

Syntax

Description

AffectedSections

Example

See Also


�

EXTERN

Function statement RDBMS dependentMust appear at the beginning when used in a form script

�

��

� ��

�- ��/��

��

�%��($�

The STORED keyword is supported for INFORMIX, INGRES, and SYBASE SQLServer.

type_specifier The ACCELL/SQL type of the value returned by the function. For Cor ACCELL functions, valid types are BINARY, NUMERIC, FLOAT,AMOUNT, BOOL, STRING, DATE, TEXT, TIME, DBMS_ERROR,and TIMER. The keyword VOID as a type_specifier indicates that theexternal function does not return a value.

(INFORMIX, INGRES, and SYBASE SQL Server only) For an INFORMIX STORED function, the only valid type isROW_VALUED. For an INGRES STORED function, the only validtype is NUMERIC. For a SYBASE SQL Server STORED function,valid types are NUMERIC or ROW_VALUED.

function_nameThe name of the external function. The form and length of the Clanguage function name depends on the C compiler. The form andlength of the ACCELL/4GL function name follows ACCELL/SQLvariable name rules.

(INFORMIX, INGRES, and SYBASE SQL Server only) For a STOREDfunction, the name of an INGRES database procedure or anINFORMIX or SYBASE SQL Server stored procedure.

The specified function name (or stored procedure name) can bedeclared in only one EXTERN statement per form script.

Syntax

Support

Arguments


EXTERN

formal_parameter_listA list of ACCELL/SQL variables that are the parameters passed to theexternal function.

Parameter names are separated by commas. If a parameter ispreceded by the keyword RESULT, the parameter can be set in theexternal function and used in the script.

Reference parameters are preceded by one of the followingkeywords:

REFERENCE REFREFERENCE LIST REF LISTREFERENCE MATRIX REF MATRIX

For a DBMS_ERROR function, a single LIST parameter is required.

(SYBASE SQL Server only) When the function type is STORED, theformal_parameter_list must consist of variable names that are thesame as the parameters specified in the stored procedure definition. Ifa variable name is preceded by the keyword RESULT, the variable isused to store a RESULT value returned by the stored procedure.

event_ID For a TIMER event, identifies the current timer.

The EXTERN statement declares an external function within a form script file. Thisstatement is the declaration for a function whose definition is not in the same file asthe function call. A function declaration notifies the ACCELL/SQL compiler that thefunction variable is not defined within the script but refers to an external function. Clanguage functions and global functions must be declared with the EXTERNstatement.

The EXTERN statement must correspond to the definition of the external function.This external function can be written in the C language (C) or in the ACCELL/4GLlanguage (ACCELL).

Description


�

EXTERN

For an ACCELL/4GL function, the EXTERN statement must match the definition ofthe global function. The difference between the function header in the definition andthe EXTERN statement is the presence of the keyword EXTERN. You do not have tomatch the function’s actual parameter names in the EXTERN statement.

For a C language function, the EXTERN statement must list the ACCELL/SQL datatype that corresponds to the function’s return type, the function name, and thefunction parameters. To set a value in the application through the parameter list, theparameter to contain the value must be preceded by the keyword RESULT.

All subsequent uses of a function that is declared in the EXTERN statement must becompatible with the function’s declaration.

EXTERN statements must be the first statements in a form script.

��-

��

��4�� 5�

The STORED keyword declares an INFORMIX or SYBASE SQL Server storedprocedure or an INGRES database procedure. The EXTERN statement mustcorrespond to the RDBMS definition of the stored procedure; the definition of thestored procedure is not included in form script. A type_specifier of either NUMERICor ROW_VALUED is required. The variable names listed in theformal_parameter_list must match the parameter names specified in the storedprocedure definition.

This statement is not valid in any event section. EXTERN must be the first line of aform script.

This EXTERN statement declares an external C function named paycalc( ) that has asthree value parameters principal, rate, and term. It returns a FLOAT value.

EXTERN C FLOAT FUNCTION paycalc(principal,rate,term)

AffectedSections

Example


EXTERN

The next EXTERN statement declares an external ACCELL/4GL function namedcalculate_pay( ). This global function has three arguments: two are value parameters(gross_salary and days_in_period) and one is a result parameter (taxes). Thefunction returns an AMOUNT value.

EXTERN ACCELL AMOUNT FUNCTION calculate_pay(gross_salary, days_in_period, RESULT taxes)

The following EXTERN statement declares a NUMERIC stored procedure namedsp_sum( ) that has two parameters and returns a numeric value.

EXTERN STORED NUMERIC FUNCTION sp_sum(a,b);

The following EXTERN statement declares a ROW_VALUED stored procedurenamed sp_nbrs( ) that has two parameters and returns a RESULT value.

EXTERN STORED ROW_VALUED FUNCTION sp_nbrs(RESULT a, b);

The sp_nbrs( ) stored procedure definition contains an OUTPUT parameter thatcorresponds to the EXTERN statement RESULT parameter.

CREATE PROC sp_nbrs @a int OUTPUT, @b int

AS SELECT . . .

CREATE TIMER EVENT, DEINSTALL, DELETE TIMER EVENT, FUNCTION,INSTALL, SETsp_compute$( ), sp_return$( ), sp_select$( )“Creating Functions” in ��)��*��#$+,��(��

SYBASE SQLServer

See Also


�

FIELD


��

� ��-��

��

��

��

+,��,��

��

"� � �

field_name The name of the form field associated with the FIELD subsections.This form field name must match the Field Name entry defined on aField Definition form in ACCELL/Generator. The form field must bedefined on the script’s form.

ACCELL/Manager executes FIELD event sections in the field order (row or column)defined for the form. Each FIELD section identifies the particular form fieldreferenced by the FIELD subsections that are listed below it.

LIST identifies a one-dimensional array of fields.

MATRIX identifies a two-dimensional array of fields.

In a FIELD LIST or FIELD MATRIX section, self-referencing of arrays is permitted,where the FIELD section applies to the current cell of the array, for example:

FIELD MATRIX expenseBEFORE FIELD

IF expense[] IS UNDEFINED THENSET expense[] TO 0

SET expense[] TO 1

This statement sets the current form field to array element 1.

Syntax

Arguments

Description


FIELD

By default, a field that is not identified as a LIST or MATRIX array is a scalar(simple) variable.

The FIELD subsections are:

AFTER FIELD

BEFORE FIELD

INIT FIELD

ON FIELD

WHEN FIELD CHANGES

You can include any or all of the FIELD subsections under the FIELD subsection.

When ACCELL/Manager begins execution of the FIELD section in add/update/deletemode, it performs the FIELD subsections in the following order:

BEFORE FIELD

ON FIELD

WHEN FIELD CHANGES

AFTER FIELD

The INIT FIELD subsection is not executed when the cursor is positioned on the formfield. INIT FIELD subsections are executed only when the form is initialized.

In find mode, only the INIT FIELD subsection is executed.

The WHEN FIELD CHANGES subsection is executed only when the form field’svalue changes.

You can include the FIELD section and the FIELD subsections in both masterapplication and standard form scripts. However, they are not valid within anACCELL/4GL function.


�

FIELD

All ACCELL/4GL statements are invalid in this section. Statements must appear insubsections.

The following subsections are valid in this section:

��

��

��

��

+,��,��

This example specifies actions for a seven-row form field array (daily_expense)where the user enters expenses for each day of the week.

FIELD LIST daily_expenseON FIELD

INPUT;IF daily_expense[] IS UNDEFINED THENBEGIN

DISPLAY ’You must enter a value’ FOR FYI_MESSAGE WAIT;RESTART ON FIELD

END

AFTER FIELD, BEFORE FIELD, FORM, INIT FIELD, NEXT ACTION, ON FIELD,WHEN FIELD CHANGES

AffectedStatements

AffectedSections

Example

See Also


FOR

Repetition statement

��-��-��

��

initialization Any valid ACCELL/SQL expression. The expression is evaluatedonce at the beginning of the loop. It usually initializes the loop’scontrol variable.

logical_expressionAny ACCELL/SQL BOOL expression. The expression is evaluated atthe beginning of each loop iteration. The statement_body is executeduntil this expression becomes FALSE.

reinitializationAny valid ACCELL/SQL expression. This expression is evaluated atthe end of each loop iteration. It usually reinitializes the loop’scontrol variable.

statement_bodyAny valid ACCELL/4GL statement: either a single statement or astatement block (statements surrounded by BEGIN and END).

The FOR statement executes statement_body as long as the logical_expression isTRUE.

The FOR statement can have up to three possible expressions following the keywordFOR: the initialization expression, the logical_expression, and the reinitializationexpression. All three expressions are optional. Each one must be separated by asemicolon (;). Even if you omit one of the FOR expressions, you must still includethe terminator symbol.

Syntax

Arguments

Description


�

FOR

To execute the FOR statement, ACCELL/Manager first evaluates the initializationexpression, if it exists. The initialization expression usually initializes the FOR loop’scontrol variable. The control variable controls the number of times that the loop isexecuted.

Next, ACCELL/Manager evaluates the logical_expression. The logical_expression isthe second expression that follows the keyword FOR (if the initialization expressionexists). This expression determines the number of times the statement body isexecuted.

If the logical_expression evaluates to TRUE, the statement_body is executed. Iflogical_expression evaluates to FALSE, the FOR loop exits. If logical_expressioncontains a null value, it evaluates to FALSE.

After it has completed execution of the statement_body, ACCELL/Manager evaluatesthe reinitialization expression, if it exists. The reinitialization expression usuallyreinitializes the FOR loop’s control variable.

ACCELL/Manager continues executing the reinitialization expression, testing thelogical_expression and executing the statement_body until logical_expression isFALSE. When the logical_expression is FALSE, the FOR loop ends.


This statement displays the numbers 1 through 99 in the current form field.

FOR (SET $index TO 1; $index < 100; SET $index TO $index + 1)BEGIN

DISPLAY indexREFRESH SCREEN

END

BREAK, CONTINUE, REPEAT, WHILE“Using Script Statements” in ��)��*��

AffectedSections

Example

See Also


FORM

Required standard form header RDBMS dependent

��

�3�

�3�

��%��

�� 6��+��

��+�� 7

�� -��6��+��

��+�� 3�� 7

��

��%��0��%��1�� 3�

��

INFORMIX The data_type option can be used to override the default data typeconversions for INFORMIX DATETIME, CHAR, VARCHAR, andTEXT values.

INGRES The data_type option can be used to override the default data typeconversions for INGRES date, char, c, varchar, and text values.

ORACLE The data_type option can be used to override the default data typeconversion for ORACLE DATE, CHAR, LONG, VARCHAR2,NUMBER(x,2), NUMBER(x,0), DECIMAL, INTEGER, SMALLINT,FLOAT, and NUMBER(x,y) values.

Syntax

Support


�

FORM

SYBASE SQLServer

The data_type option can be used to override the defaultdata type conversions for SYBASE SQL Server datetime,char, varchar, and text values.

Unify DataServer The data_type option can be used to override the default data typeconversion for Unify DataServer STRING and TEXT values.

form_name The name of the form associated with the script file. This form namemust match the Form Name field entry defined on the FormDefinition form in ACCELL/Generator.

table_name The name of a database table that is to be associated with this form.This table name must match the Target Table field entry defined onthe Form Definition form in ACCELL/Generator.

target_var1 . . . target_varn Specifies the name of a target variable that references an RDBMSdate-time, numeric, string, or text column. To define multiple targetvariables, list each variable name and its data type, and separate eachdeclaration by a comma.

data_type Keyword that specifies the data type to which the target variable is tobe converted. The data type must be specified with one of thesekeywords.

AMOUNT Specifies that the value from an ORACLENUMBER(x,y), NUMBER(x,0), DECIMAL,INTEGER, or SMALLINT database column is to beconverted to an AMOUNT type target variable.

DATE Specifies that the value from a combinationdate-time database column (INFORMIX DATE,INGRES date, ORACLE DATE, SYBASE SQL Serverdatetime) is to be converted to a DATE type targetvariable.

FLOAT Specifies that the value from an ORACLENUMBER(x,2), NUMBER(x,0), DECIMAL,INTEGER, or SMALLINT database column is to beconverted to a FLOAT type target variable.

Arguments


FORM

NUMERIC Specifies that the value from an ORACLENUMBER(x,y) or NUMBER(x,2) database column isto be converted to a NUMERIC type target variable.

STRING Specifies that the value from a text type databasecolumn is to be converted to a STRING type targetvariable.

(All RDBMSs) The source database column can be a text typedatabase column or a combination date-timedatabase column. Text types are INFORMIX TEXT,INGRES varchar(n) or text, ORACLE LONG orCHAR or VARCHAR2, SYBASE SQL Server text,and Unify DataServer TEXT.

(INFORMIX, INGRES, ORACLE, and SYBASE SQLServer only) Combination date-time types are INFORMIX DATE,INGRES date, ORACLE DATE, and SYBASE SQLServer datetime.

TEXT Specifies that the value from a string type databasecolumn (INFORMIX CHARACTER(n) or VARCHAR,INGRES char, c, or varchar, ORACLE CHAR orVARCHAR2, SYBASE SQL Server char(n) orvarchar(n), Unify DataServer STRING) is to beconverted to a TEXT type target variable.

TIME Specifies that the value from a combinationdate-time database column (INFORMIX DATE,INGRES date, ORACLE DATE, SYBASE SQL Serverdatetime) is to be converted to a TIME type targetvariable.


array The name of a one-dimensional (LIST) or two-dimensional(MATRIX) array.


�

FORM

num_expr A numeric expression for delimiting the lower or upper bounds of anarray.

local_functionsThe local ACCELL/4GL function definitions for this form.

The FORM section is the required form header for a form script for a standard form.This section identifies the form, specifies the form’s target table, declares variableslocal to the form and defines local functions.

The TARGET_TABLE clause associates the script with the form’s target table. Thetarget table is the database table that is accessed when an interactive databaseoperation occurs. Interactive search, add, update, and delete operations from thisform access the target table specified by table_name. This clause is required for allforms that have a target table. The target table name must match the name specifiedfor the form in ACCELL/Generator.

The LOCAL clause lists the names of variables that are local to this form. Localvariables can be accessed by just the variable name; they do not need to be prefixedwith the form name (form_name:variable) to clarify which form they are defined on.Local variables can be referenced by successive forms.

When the LOCAL clause is used to override a default data type conversion for atarget variable, the ACCELL/SQL combiner (ACMB) verifies that the target variabletypes that are defined in the LOCAL clause match the data types that are defined inACCELL/Generator. You cannot specify the data type option in a LOCAL clause thatis in a global or local function, or for a nontarget variable.



Description


FORM


To verify whether an array has an upper bound, use the BOUNDED attribute. Todetermine the type of an array, use the DIMENSION attribute.

The local_functions clause of the FORM section defines local functions for the formscript. This local function can be called anywhere within the form script. You definelocal functions with the FUNCTION statement.

You must use the FORM section at the beginning of each standard form script. If yourform script uses external functions, the EXTERN statements must appear before theFORM statement. If you do not use external functions within the form script, FORMis the first line of the form script.

All ACCELL/4GL statements are invalid in this section except FUNCTION.

The first FORM section example defines the form payperiod. This form has no targettable, no local variables, and no local ACCELL/4GL functions.

FORM payperiod

In the following example, the orders form (target table orders) has a target fieldnamed ship_date. The target column (also named ship_date) in the database is ofdatetime data type. The default data type conversion is to DATE, but the followingLOCAL clause converts the data type for ship_date target field to TIME:

FORM orders TARGET_TABLE ordersLOCAL ship_date TIME ;

The next FORM section defines the form benefits. This form has a target table,employee. The user can perform interactive operations on the employee table. Thisform has two local variables, net_salary and net_pay. The form also has a localfunction called calculate_benefit( ). This local function also has a local variable,benefit. The benefit variable is local to the function only.

AffectedStatements

Example


�

FORM

FORM benefitsTARGET_TABLE employee

LOCAL net_salary, net_payLOCAL VOID FUNCTION calculate_benefit

(RESULT cum_benefit, benefit_rate, days_in_period)

LOCAL benefitBEGIN

SET benefit TO benefit_rate * days_in_periodSET cum_benefit TO cum_benefit + benefitRETURN

END

The following clause declares a one-dimensional array with a subscript range ofseven elements from 0 to 6.

LOCAL LIST days_of_the_week[0 TO 6]

The next clause declares a two-dimensional array with a bounds of three for bothrows and columns.

LOCAL MATRIX tic_tac_toe[1 TO 3,1 TO 3]

The next example declares a two-dimensional array called company_records havingnine columns in each row. When records are selected, approximately 100 records areexpected.

LOCAL company_records[1 TO UNKNOWN ESTIMATING 100,1 TO NUM_COLUMNS]. . .BEFORE FORM

SET NUM_COLUMNS TO 9

BOUNDED, COLUMN_LOWER_BOUNDS, COLUMN_UPPER_BOUNDS,LIST_INDEX, LIST_LOWER_BOUNDS, LIST_UPPER_BOUNDS,ROW_LOWER_BOUNDS, ROW_UPPER_BOUNDS, TARGET_TABLE attributes APPLICATION, FIELD, FUNCTION��#$+,��(��

See Also


FUNCTION

Function statement

�� 3��

��

��%��

�� 6��+��

��+�� 7

�� -��6��+��

��+�� 3�� 7

��

� ��

�3�

�3�

return_type The ACCELL/SQL data type that the function returns. Valid datatypes are: AMOUNT, BOOL, DATE, FLOAT, NUMERIC, STRING,TIME, TEXT, BINARY, TIMER, and DBMS_ERROR. If the functiondoes not return a value, use the keyword VOID as the return_type.For an RDBMS error-handling function, specify the return_type asDBMS_ERROR.

function_nameThe name of the function. Do not use the dollar sign ($) character asthe last character of a function name.

parameter_type One of the following parameter types:

REFERENCE REFREFERENCE LIST REF LISTREFERENCE MATRIX REF MATRIXRESULT VALUE

Syntax

Arguments


�

FUNCTION

parameter A function parameter name. To define a value parameter, include justthe parameter name in the parameter list. To define a resultparameter, include the keyword RESULT in front of the parametername.


array The name of a one-dimensional (LIST) or two-dimensional(MATRIX) array.

num_expr A numeric expression for delimiting the lower and upper bounds ofan array.

function_bodyThe statements that define the function task. Some ACCELL/4GLstatements are invalid in a function body. Invalid statements arelisted in Affected Statements.

The FUNCTION statement defines an ACCELL/4GL function. A function containsACCELL/4GL statements. Functions can have parameters and they can return values.Local functions cannot be used recursively.

There are two types of ACCELL/4GL functions: global functions and local functions.You can call a global function from any form script. To define a global function,include the function definition in a separate script file, and include an EXTERNstatement in each script that calls the global function.

Within a global function, you can define one or more local functions. TheFUNCTION statement must be used after the global function header and any existinglocal variable definitions.

The FUNCTION statement cannot be used within a local function.

To declare a global function, use the EXTERN statement in the script where you callthe global function. You can also declare a global function in the master applicationform script in the REQUIRED FUNCTIONS clause of the APPLICATION section.

Description


FUNCTION




To verify at runtime whether an array has an upper bound, use the BOUNDEDattribute. To determine the type of an array, use the DIMENSION attribute.

You can call a local function only from within the script in which it is defined.ACCELL/Manager treats a local function as another ACCELL/4GL event section. Todefine a local function, include the function definition in the FORM section, after theLOCAL clause. You do not need to declare local functions.

Functions can have parameters. Parameters are not required in a function, but if afunction does have a parameter list, this list must include the parentheses.

These function parameters can be value parameters, reference parameters, or resultparameters. Changing the value of a value parameter within the function does notaffect the value of the associated argument in the calling script. Changing the value ofa result parameter does affect the argument value: ACCELL/Manager copies the resultparameter value into the associated function argument when the function exits.


�

FUNCTION

Array variables can be passed as parameters to local and global functions byreference only. Individual array elements can be passed by value, reference, or result.

To call a function, include the function name and any associated function argumentsin parentheses. Even if a function does not have parameters, you must include theopen and close parentheses in the function call. If the function returns a value, youcan save this value by assigning the return value to a variable with a SET statement.

Do not pass the NULL constant into a function without first providing a data typewith a type-conversion system function.

The following statements are invalid in a function:

��

��0

��1��#��$��0

�- ��

��1�

��- ��

��2�� 1��

��2��

��

�1��

This first FUNCTION statement example defines a local function calledcalculate_benefit( ). This local function has three parameters: one result parameter(cum_benefit) and two value parameters (benefit_rate and days_in_period). Thisfunction also has a local variable, benefit. The calculate_benefit( ) function does notreturn a value.

LOCAL VOID FUNCTION calculate_benefit(RESULT cum_benefit, benefit_rate, days_in_period)

LOCAL benefit

BEGINSET benefit TO benefit_rate * days_in_periodSET cum_benefit TO cum_benefit + benefit

END

AffectedStatements

Example


FUNCTION

The next function defines a global function called calculate_pay( ). This globalfunction has three parameters: one result parameter (taxes) and two value parameters(gross_salary and days_in_period).

This function also has two local variables, net_salary and net_pay. Thecalculate_pay( ) function returns the AMOUNT value of net_pay. Defined within theglobal calculate_pay( ) function is the local function, get_netpay( ).

AMOUNT FUNCTION calculate_pay(gross_salary, days_in_period, RESULT taxes)

LOCAL net_salary, net_pay

LOCAL AMOUNT FUNCTION get_netpay (gross_salary, RESULT taxes)

LOCAL the_taxrate, net_pay

BEGINSET the_taxrate TO

SELECT tax_rate FROM ratesWHERE lower_sal <= gross_salary AND upper_sal >= gross_salary

SET taxes TO (gross_salary * the_taxrate)SET net_salary TO gross_salary – taxesRETURN (net_salary)

END

BEGINSET taxes TO 00.00SET net_salary TO get_netpay(gross_salary, taxes)SET net_pay TO (net_salary / days_in_period)RETURN (net_pay)

END

BOUNDED, COLUMN_LOWER_BOUNDS, COLUMN_UPPER_BOUNDS,LIST_INDEX, LIST_LOWER_BOUNDS, LIST_UPPER_BOUNDS,ROW_LOWER_BOUNDS, ROW_UPPER_BOUNDS attributesAPPLICATION, CREATE TIMER EVENT, DEINSTALL, EXTERN, FORM,INSTALL, RETURN“Creating Functions” in ��)��*��#$+,��(��

See Also


�

GRANT


�� 1��/��

��

�� 3� � � �� 3� � � �� 3� � � ��1�� 3� � � ��

�� '��*��,�� ,��0� ��'�� '��

1��3� � ��+� ,�� 1 ��.�


column_name The name of a table column.


user_name The database user’s name.

The GRANT statement defines user privileges.



Syntax

Support

Arguments

Description


GRANT


This GRANT statement gives SELECT privileges on the employees table to thePUBLIC user.

GRANT SELECT (emp_name, emp_id, emp_addr) ON employees to PUBLIC;

DELETE, INSERT, REVOKE, SELECT, UPDATE��#$+,��(��Documentation provided by the RDBMS vendor

AffectedSections

Example

See Also


�

IF

Decision statement

�� ,��0��1��

logical_expressionAny ACCELL/SQL expression that evaluates to a BOOL value. Theexpression determines whether statement_body1 is executed. If thereis an ELSE clause, this expression determines whetherstatement_body1 or statement_body2 is executed.

statement_body1Any valid ACCELL/SQL statement: either a single statement or astatement block (statements surrounded by BEGIN and END). Thisstatement body is executed if logical_expression is TRUE.

statement_body2Any valid ACCELL/SQL statement: either a single statement or astatement block (statements surrounded by BEGIN and END). Thisstatement body is executed if logical_expression is FALSE.

The IF statement conditionally executes statement_body1. To execute the IFstatement, ACCELL/Manager first evaluates logical_expression. Thelogical_expression determines whether statement_body1 is executed:

If the logical_expression is TRUE, statement_body1 is executed.

If there is an ELSE clause and logical_expression is FALSE, ACCELL/Managerexecutes statement_body2. If there is no ELSE clause and logical_expression isFALSE, ACCELL/Manager skips over statement_body1 and continuesexecution with the next statement.

If the logical_expression contains a null value, it evaluates to FALSE.

Syntax

Arguments

Description


IF


The first IF statement example sets the order terms to the default value of ’2% 10, net30 days’ if the user does not enter a value for it.

IF ( forders:ord_terms IS UNDEFINED ) THENSET forders:ord_terms TO ‘2% 10, net 30 days’

The next example checks the value of the pay_periods variable to determine theaction to take. If pay_periods is 0, ACCELL/Manager sets period_sal to NULL. Ifpay_periods is any value other than 0, ACCELL/Manager uses that value to calculatethe value of the period_sal variable.

IF ( pay_periods = 0) THENSET period_sal TO NULL

ELSESET period_sal TO total_sal / pay_periods

SWITCH“Using Script Statements” in ��)��*��

AffectedSections

Example

See Also


�

INIT FIELD


��

��

��

��

+,��,��

��

"� � �


ACCELL/Manager executes all INIT FIELD sections after the form’s initialization butbefore the BEFORE FORM section. To initialize the form, ACCELL/Manager displaysthe form and then executes any INIT FIELD sections for the form script’s FIELDsections.

The order in which ACCELL/Manager executes the INIT FIELD subsections is notnecessarily the order that the fields appear on the form or in the script. Do not includestatements that depend on a particular order of execution in INIT FIELD.

The INIT FIELD section is a subsection of the FIELD section. You must introduce theINIT FIELD subsection with the FIELD section. The FIELD section identifies theparticular form field to which the INIT FIELD subsection refers.

If your form script includes a FIELD section for the field for one of the other FIELDsubsections, do not repeat the FIELD section. Only one FIELD section is required perform field.

Syntax

Arguments

Description


INIT FIELD

You can use this subsection to initialize those field attribute values that are notexpected to change during the form’s execution. INIT FIELD can also be used tooverride the default field attribute values set in ACCELL/Generator.

Using the ENABLE ZOOM statement in the INIT FIELD subsection makes thecurrent form field zoom enabled in add/update/delete and find mode. If you want thefield to be zoom enabled in add/update/delete mode only, put ENABLE ZOOM in theBEFORE FIELD subsection.

In a master application form script, all INIT FIELD subsections are executed justafter the BEFORE APPLICATION section and before the BEFORE FORM section. Ina standard form script, all INIT FIELD subsections are executed just before theBEFORE FORM section.


�- ��

��

��1�

��- ��

��2�� 1��

��2��

��

��

AFTER FIELD, BEFORE APPLICATION, BEFORE FIELD, BEFORE FORM,ENABLE ZOOM, FIELD, ON NEXT ACTION, FIELD, WHEN FIELD CHANGES

AffectedStatements

See Also


�

INPUT

Input statement

��1�

The INPUT statement retrieves information that the user enters in the current formfield. When ACCELL/Manager reaches an INPUT statement in an ON FIELDsubsection, it pauses execution until the user enters data or presses ��.

When the user moves to another form with either �� (to a next form) or�� (to a zoom form), ACCELL/Manager suspends execution of the ON FIELDsubsection. When the user returns to this form, execution resumes at the beginning ofthe ON FIELD subsection.

The INPUT statement is affected by the current value of the field’s attributes. If afield’s STOP_FOR_INPUT attribute is set to FALSE, then the INPUT statement is notexecuted. However, the remaining statements in ON FIELD are executed regardlessof the field’s STOP_FOR_INPUT setting.

If the field’s UPDATEABLE attribute is set to FALSE, the user cannot enter new datain the field when the form is in add/update/delete mode. If the field’s FINDABLEattribute is set to FALSE, the user cannot enter search criteria in the field when theform is in find mode.

If the field’s REQUIRED attribute is set to TRUE, the user must enter data beforebeing allowed to continue to the next form field.

You can test information entered by the user in the ON FIELD section. If the input isnot correct, you can require that the user reenter it by including the RESTART ONFIELD statement in ON FIELD.

You can use the INPUT statement only in the ON FIELD section. If you omit theINPUT statement, ACCELL/Manager does not pause to accept data.

Syntax

Description


INPUT

This statement is valid only in an ON FIELD section.

This script sample receives input from the field sc_name_field. After the user entersa value, the input value is passed to a user function, namechk( ).

If namechk( ) returns FALSE, the input is not valid. The code then displays an errormessage in the fyi_message system information field and restarts the ON FIELDsection.

FIELD sc_name_field

ON FIELD INPUTIF (NOT namechk($sc_name_field)) THEN

BEGINDISPLAY ’Letters, blanks, apostrophes, hyphens only’

FOR FYI_MESSAGE WAITRESTART ON FIELD

END

ON FIELD, RESTART ON FIELD

AffectedSections

Example

See Also


�

INSERT


�� '��*�� 2��/��%��



table_name The name of a database table. The new row is added to this table.

db_column_listA list of columns in table_name separated by commas. This listcontains the columns in the new row that will have the values invalue_list assigned to them.

value_list A list of constants, variables, or functions separated by commas.Each expression is evaluated and the resulting value is assigned tothe corresponding table column variable in db_column_list.

The INSERT statement initiates a noninteractive insert operation to create a new arow in database table, table_name. The INSERT statement does not cause executionof the BEFORE ADD and AFTER ADD sections.

The INSERT statement allows access to only one database table at a time. You cannotinclude more than one table name in this statement.

You can use the VALUES clause to assign values to the db_column_list, or you canuse a SELECT statement to copy values from another table.

Syntax

Support

Arguments

Description


INSERT

The SELECT statement cannot refer to the table into which the new rows are to beinserted, and the number of columns selected must match the number of columnsspecified in db_column_list.

Likewise, for the VALUES clause, the db_column_list and the value_list must havethe same number of elements.

The first value in initial_value_list or the first selected column is assigned to the firstcolumn in the db_column_list, the second initial value is assigned to the secondcolumn, and so on until the end of both lists. For this reason, corresponding values orselected columns and the db_column_list must be type compatible.

When inserting a row, the database must have a value for every column in the row.The database must assign the initial column value for any table columns not in thedb_column_list, either the column default value or a null value. If no value isspecified for a column defined as NOT NULL, an error is returned.

The INSERT statement issues an exclusive lock request on the new row. After theinsert operation is completed, the lock remains until the current transaction iscommitted.

You can use the ACCELL/SQL system function status$( ) to test the success of anoninteractive insert operation. If the user does not have insert privilege, thestatus$( ) function returns a status code of SS_WRACS.



�

INSERT

This INSERT statement assigns the values 2000, “Table, Artists”, and $49.95 to thest_number, st_description, and st_unit_price columns of the stock table. However,if the noninteractive insert operation fails, the user is notified and the transaction isrolled back.

INSERT INTO stock (st_number, st_description, st_unit_price) VALUES (2000, ’Table, Artists’, $49.95);

IF ( status$() <> SS_NORM ) THENBEGIN

ROLLBACK WORKDISPLAY ’Noninteractive insert failed; aborting tx’


DELETE, DELETE CURRENT RECORD, EXECUTING, GRANT, SELECT,UPDATE, UPDATE CURRENT RECORD, XLOCKstatus$( ) ��#$+,��(��Documentation provided by the RDBMS vendor

Example

See Also


INSTALL

Function statement

�� ,��

�� /��

�/�� -��1 ��

�� '��

function_nameSpecifies the global function name that is to be called when anRDBMS error occurs.

expression_list One or more status$( ) return values, separated by commas. If aDELETE, SELECT, or UPDATE operation affects no rows, status$( )returns a value of SS_NOREC.

handler_id A variable that identifies the particular installation of the errorhandler.

The INSTALL statement installs a global handler function. The function_name mustbe declared by an EXTERN statement in the form script where the function isinstalled.

To deinstall a handler function, use the DEINSTALL statement.


Syntax

Arguments

Description

AffectedSections


�

INSTALL

This statement installs a function that is called when a database deadlock occurs:

BEFORE APPLICATIONINSTALL DBMS_ERROR HANDLER deadlock_handler FOR EVENTS SS_DEADLOCK

IDENTIFIED BY $deadlockid

This statement installs a function that is called when any RDBMS error occurs exceptwhen a duplicate key or no records are found:

BEFORE FORMINSTALL DBMS_ERROR HANDLER gen_handler

FOR EVENTS EXCEPT SS_DUPK, SS_NORECIDENTIFIED BY $genid

DEINSTALL, EXTERN, FUNCTION, status$( )“Creating Functions” in ��)��*��

Example

See Also


NEXT ACTION


��- �� /��

action_keywordThe next action that is to be executed. Valid next actions are:

��1��

��0

��

��

��

�-�

��

��

,��1

��

��- ��

��- ��

��- ��

��- ��

��- � ��

1��/��

1��/��

1��/��

1��/��

1��/��

�� ,��1

0

numeric_expressionA defined, non-null expression for the nth record in the selected set.If the record specified is after the current record, the ON NEXTRECORD SECTION is executed. If the record specified is before thecurrent record, the ON PREVIOUS RECORD section is executed. Ifthe record number is the current record, the record is reinitialized.

The NEXT ACTION statement simulates the execution of an ACCELL/SQL usercommand. NEXT ACTION forces execution of a user command without having torely on the user to press a command key.

ACCELL/Manager discontinues execution of the current event section at the NEXTACTION statement and executes the specified action as if the user had pressed thecommand key associated with the NEXT ACTION statement.

For example, when ACCELL/Manager encounters a NEXT ACTION IS FINDstatement, it performs the following operations:

discontinues execution of the current event section at the NEXT ACTIONstatement

automatically performs a clear-to-find operation and enters find mode

Syntax

Arguments

Description


�

NEXT ACTION

executes the ON CLEAR TO FIND section, if it exists

evaluates the clear-to-find expressions

executes the BEFORE FIND section, if it exists

searches the form’s target table for the specified search criteria, creating aselected set record for each selected target table row

executes the ON FIND section, if one exists, for each selected set record

executes the AFTER FIND section, if one exists

The following table lists next action statements and the equivalent ACCELL/Managercommands:

��- �� *�*�* �89$5!&��(��:!�!;� ��<<!�=

��1��

��0

��

��

��

�-�

��

��

,��1

��

��- ��

��- ��

��- ��

��- ��

��- � ��

1��/��

1��/��

1��/��

1��/��

1��/��

�� ,��1

0

��

��

��

��

��

��

��

��

��

��

��

��

��

��

��

��

��

��

��

��

��

��


NEXT ACTION


�� 11��

��11��

��

��

��

��-�

��

+,��,��

The NEXT ACTION IS RECORD numeric_expression statement is invalid in the ONNEXT RECORD section.

The NEXT ACTION IS NEXT_FIELD, NEXT ACTION IS NEXT_TAB, NEXTACTION IS PREVIOUS_FIELD, and NEXT ACTION IS PREVIOUS_TAB statementsare valid only in the AFTER FIELD, BEFORE FIELD, and ON FIELD sections.

WarningDo not include a next action in the event section that the action invokes unlessyou provide some way to conditionally execute the NEXT ACTION statement. Forexample, if you include the statement NEXT ACTION IS EXIT in the ON EXITsection, the statement creates an infinite loop.

This NEXT ACTION statement automatically performs a clear-to-add operation whenthe user presses �� from the last field of the last record in the selected set.

IF ( current_record_num$() = current_record_count$() ) THENNEXT ACTION IS CLEAR_TO_ADD

AffectedSections

Example


�

NEXT ACTION

This example notes the record number of the highest paid employee during a findoperation. The user can go directly to this record by pressing function key F20.

DEFINE COMMAND max_salaryKEY IS ’NONE<KEY>F20’FIND_LABEL IS ’Max Sal’FIND_ACTION IS ’DISABLED’AUD_ACTION IS ’DISABLED’NEXT ACTION IS RECORD $max_salary_record

ON FINDSET COMMAND max_salary:FIND_ACTION TO ’ENABLED’IF $salary > $max_salary THEN

BEGINSET $max_salary TO $salarySET $max_salary_record TO current_record_num$()

END

CLEAR_FIND_EXP attributeAFTER ADD, AFTER DELETE, AFTER FIELD, AFTER FIND, AFTER UPDATE,BEFORE ADD, BEFORE DELETE, BEFORE FIELD, BEFORE FIND, BEFORE RECORD, BEFORE UPDATE, FIELD, INIT FIELD, ON CLEAR TO ADD,ON CLEAR TO FIND, ON EXIT, ON FIELD, ON FIND, ON NEXT FORM, ON NEXT RECORD, ON PREVIOUS FORM, ON PREVIOUS RECORD, WHEN FIELD CHANGES

See Also


ON CLEAR TO ADD

Add section Master application and standard form scripts

��

��


ACCELL/Manager executes the ON CLEAR TO ADD section after a clear-to-addrequest. The request can be either explicit or implicit. An explicit clear-to-addoperation occurs when the user presses ��.

An implicit clear-to-add operation occurs under any of the following conditions:

The NEXT ACTION IS CLEAR_TO_ADD statement is executed.

The form is initialized to add/update/delete mode because theAUD_ON_ENTRY form attribute is TRUE.

The CLEAR_AFTER_AU form attribute is TRUE.

The last record in the selected set is deleted.

The clear-to-add operation puts the current form in add/update/delete mode. Inadd/update/delete mode, ACCELL/Manager interprets input data as field values.

You can use this section to set variable default values by using the SET statement todirectly assign the variable values. Do not set clear-to-add expressions in ON CLEARTO ADD. ACCELL/Manager evaluates these expressions before executing the ONCLEAR TO ADD section.

The ON CLEAR TO ADD section is not executed by the CLEAR TO ADD statement.

Syntax

Arguments

Description


�

ON CLEAR TO ADD


��

��

��

��

��

��

��

��

��

��

��

��

��

AFTER ADD, BEFORE ADD, CLEAR TO ADD, NEXT ACTION, ON CLEAR TO FIND“Add/Update/Delete Mode” in ��

AffectedStatements

See Also


ON CLEAR TO FIND

Find section Standard form script only with target table

��

��


ACCELL/Manager executes the ON CLEAR TO FIND section after a clear-to-findrequest. The clear-to-find request can be either explicit or implicit. An explicitclear-to-find operation occurs when the user presses �� .

An implicit clear-to-find operation occurs under any of the following conditions:

The NEXT ACTION IS CLEAR_TO_FIND statement is executed.

The NEXT ACTION IS FIND statement is executed.

The form is initialized to find mode because the AUD_ON_ENTRY andAUTO_FIND form attributes are set to FALSE.

The clear-to-find operation can be used only on forms that have target tables. Thisrequest puts the current form in find mode. In find mode, ACCELL/Manager interpretsinput data as search criteria for a database search.

You can abort the clear-to-find operation by using the REJECT OPERATIONstatement in this section.

You can use this section to set search criteria values by using the SET statement todirectly assign the Search Ranges values or the SQL_OPTIONAL_CONDITION andSQL_ORDER_BY_COLUMN attributes. You can also set clear-to-find expressions inON CLEAR TO FIND. ACCELL/Manager evaluates these expressions after executingthe ON CLEAR TO FIND section.

Syntax

Arguments

Description


�

ON CLEAR TO FIND


��

��

��

��

��

��

��

��

��

��

��

��

��

This script sample sets the clear-to-find expression for the variable ord_name to allvalues greater than or equal to 500.

ON CLEAR TO FINDSET forders:ord_num:CLEAR_FIND_EXP TO 500 =>

CLEAR_FIND_EXPAFTER FIND, BEFORE FIND, ON FIND, ON CLEAR TO ADD,REJECT OPERATION“Attributes Summary” section of this manual“Find Mode” in ��

AffectedStatements

Example

See Also


ON EXIT


��

��


ACCELL/Manager executes the ON EXIT section when one of the following eventsoccurs:

The user presses �� .

ACCELL/Manager encounters a fatal error.

The user selects the “Exit” option from a Next Form menu.

The NEXT ACTION IS EXIT statement is executed.

The EXIT statement is executed.

In a master application form script, ACCELL/Manager executes the ON EXIT sectionwhen ACCELL/Manager exits the application with the USING EXIT clause in theCHOOSE FIRST FORM section. In a standard form script, ACCELL/Managerexecutes the ON EXIT section when ACCELL/Manager exits the application with theUSING EXIT clause in the CHOOSE NEXT FORM section.

When ACCELL/Manager exits the application, it executes only the ON EXIT sectionof the current form. ON EXIT sections in other form scripts are not executed.

The NEXT ACTION statement cannot be used in the ON EXIT section. To initiate anaction, use the QUEUE COMMAND statement.

When ACCELL/SQL encounters a fatal error, it aborts all transactions. If you want tosave the current transaction, use the COMMIT WORK statement in ON EXIT. Youcan use the status$( ) system function to determine whether ON EXIT is executingbecause of an �� request (status$( ) = SS_NORM) or a fatal error(status$( ) <> SS_NORM).

Syntax

Arguments

Description


�

ON EXIT

You can use this event section to perform cleanup activities specific to the currentform before leaving the application. It can also be used to prevent an exit from thecurrent form.

During execution of the ON EXIT section, if the user presses ��

while ACCELL/Manager is waiting for a response to a message, the application isterminated, regardless of whether the REJECT OPERATION statement was used inthis section. If you do not want to allow the user to be able to terminate theapplication from within ON EXIT, you can temporarily disable the ��

�� command by using the SET COMMAND statement at the start of theON EXIT section. Repeat SET COMMAND at the end of the ON EXIT section toenable the �� command again.


��

��

��

��

��

��

��

��

The following script sample notifies the user that the ��

command cannot be used to exit the current form. The user is not permitted to leavethe application from this form.

ON EXIT DISPLAY ’You cannot exit this application from this form!’ FOR FYI_MESSAGE WAIT REJECT OPERATION

In the preceding example, if the user presses �� whileACCELL/SQL is waiting for a response, the application will be exited.

AffectedStatements

Example


ON EXIT

The following script sample guarantees that the user cannot exit from this form. Inthis example, if the user presses �� while ACCELL/SQL iswaiting for a response to the FYI message, the command will have no effect.

ON EXIT SET COMMAND ”EXIT” : ACTION TO ’DISABLED’ ; DISPLAY ’You cannot exit this application from this form!’ FOR FYI_MESSAGE WAIT ; REJECT OPERATION ; SET COMMAND ”EXIT” : ACTION TO ’ENABLED’ ;

AFTER APPLICATION, CHOOSE FIRST FORM, CHOOSE NEXT FORM, EXIT,NEXT ACTION, QUEUE COMMAND, REJECT OPERATION

See Also


�

ON FIELD


��

��

��

��

��

��

�

��


ACCELL/Manager executes the ON FIELD section immediately after the BEFOREFIELD section. ACCELL/Manager executes all statements in ON FIELD up to theINPUT statement. At the INPUT statement, ACCELL/Manager pauses execution andwaits for the user to enter input. After the input is entered, ACCELL/Manager resumesexecution of ON FIELD.

The ON FIELD section is a subsection of the FIELD section. You must introduce theON FIELD subsection with the FIELD section. The FIELD section identifies theparticular form field to which the ON FIELD section refers.

If your form script includes a FIELD section for one of the other FIELD subsections,do not repeat the FIELD section. Only one FIELD section is required per form field.

The use of the ON FIELD subsection is optional. If you do not include the ON FIELDsubsection, ACCELL/Manager automatically performs the INPUT statement after theBEFORE FIELD subsection. However, if you use ON FIELD, you must include theINPUT statement somewhere within ON FIELD if you want input accepted.ACCELL/Manager does not perform an automatic INPUT if the FIELD section has anON FIELD subsection.

ON FIELD executes whether the form field’s STOP_FOR_INPUT attribute is TRUEor FALSE. If STOP_FOR_INPUT is FALSE, ACCELL/Manager does not execute theINPUT statement.

Syntax

Arguments

Description


ON FIELD

The �� and �� user commands suspend execution of the ON FIELDsubsection at the INPUT statement. When the user returns to this form,ACCELL/Manager resumes execution at the beginning of the ON FIELD subsection ofthe field that was suspended.

You can perform input checking in the ON FIELD subsection by includingappropriate input verification statements. If the input verification fails, you can usethe RESTART ON FIELD statement. With RESTART ON FIELD, ACCELL/Managergives the user another chance to enter input by starting execution of the ON FIELDsubsection again.


��

��

��

��

��

This script sample receives input from the field sc_name_field. After the user entersa value, the input value is passed to a user function, namechk( ). If namechk( )returns FALSE, the input is not valid. Then an error message is displayed and the ONFIELD section is restarted.

FIELD sc_name_field




END

AFTER FIELD, BEFORE FIELD, FIELD, INIT FIELD, INPUT, NEXT ACTION,RESTART ON FIELD, WHEN FIELD CHANGES

AffectedStatements

Example

See Also


�

ON FIND

Find section Standard form script with target table

��

��


ACCELL/Manager executes the ON FIND section each time a target table row isselected in an interactive find operation. An interactive find operation occurs underthe following conditions:

The user presses �� .

The NEXT ACTION IS FIND statement is executed.

The form begins execution with AUTO_FIND set to TRUE (andAUD_ON_ENTRY set to FALSE).

This section contains statements that are executed for each row that meets the searchcriteria. You can think of this section as a loop that is executed once for each targettable row found. Within the ON FIND section, you can process each row as it isfound, using the target variables to obtain the row’s column values.

In this section, you can use the REJECT RECORD statement to prevent a record frombeing added to the selected set. If the selected row is not rejected, ACCELL/Managercreates a selected set record for the row. The REJECT RECORD statement can beused only in the ON FIND section.

After ACCELL/Manager has executed the ON FIND section for the last selected rowin the selected set, it begins execution of the AFTER FIND section.

The ON FIND section can be used to increment counts, to verify that a record can beadded to the selected set and to calculate totals.

Syntax

Arguments

Description


ON FIND


��

��

��

��

��

��

��

��

��

In this example, only target table rows where the target table field num_sold value isgreater than 0 are placed in the selected set. Then the total number of items sold iscalculated as the selected set is created.

ON FINDIF num_sold > 0 THEN

SET $grand_total TO $grand_total + num_soldELSE

REJECT RECORD

AFTER FIND, BEFORE FIND, DELETE SELECTED ROW, ON CLEAR TO FIND,NEXT ACTION, REJECT RECORD“Attributes Summary” chapter of this manual

AffectedStatements

Example

See Also


�

ON NEXT FORM


��

��


ACCELL/Manager executes the ON NEXT FORM section after a next form request.The next form request can be either explicit or implicit. An explicit next formoperation occurs when the user presses ��. An implicit next form operationoccurs when the NEXT ACTION IS NEXT_FORM statement is executed or when thecurrent form has no form fields with the STOP_FOR_INPUT field attribute set toTRUE.

After execution of ON NEXT FORM is completed, ACCELL/Manager executes aChoose Form statement: CHOOSE NEXT FORM in a standard form script andCHOOSE FIRST FORM in a master application form script. The first section to beexecuted on the next form is BEFORE FORM.

You can abort the request by using the REJECT OPERATION statement in thissection.

Use this section to keep an unauthorized user from going on to the next form, toverify that all required input has been entered, to perform checks on the state of theform, or to save any uncommitted changes made by the user.

Syntax

Arguments

Description


ON NEXT FORM


��

��

��

��

��

��

��

��

��

��

��

��

In this example, if the user presses �� but has not completed the co_keyfield, an error message is displayed, and the operation is rejected.

ON NEXT FORMIF fcompany:co_key IS UNDEFINED THENBEGIN

beep$(1)DISPLAY ’You must select a Company before going to the next form.’FOR FYI_MESSAGE WAITREJECT OPERATION

END

AFTER FORM RETURN, AFTER ZOOM, BEFORE FORM, CHOOSE FIRSTFORM, CHOOSE NEXT FORM, NEXT ACTION, ON PREVIOUS FORM, REJECTOPERATION

AffectedStatements

Example

See Also


�

ON NEXT RECORD


��

��


ACCELL/Manager executes the ON NEXT RECORD section when it receives arequest to make a next record in the selected set current. A next record becomescurrent when any of these events occurs:

The user presses one of the following record commands: ��

��

��

The NEXT ACTION statement is executed with one of the following nextactions:NEXT ACTION IS NEXT_RECORDNEXT ACTION IS LAST_RECORDNEXT ACTION IS NEXT_SET

You can abort the ��, ��, or �� request by using theREJECT OPERATION statement in this section. To determine which of the usercommands is executed ON NEXT RECORD, use the last_command$( ) systemfunction.

ACCELL/Manager executes the ON NEXT RECORD section when the user presses ��, ��, or ��, even when the selected set has nonext record.

Syntax

Arguments

Description


ON NEXT RECORD


��

��

��

��

��

��

��

��

��

��

��

��

��

��

This script sample checks the state of the current record when the user presses ��. If the current record is not stored, the �� command isrejected. If the current record is stored, ACCELL/Manager makes the next record inthe selected set the current record.

ON NEXT RECORDIF ( NOT is_current_record_stored$() )THEN

BEGINDISPLAY

’WARNING! The current record has not been updated’FOR FYI_MESSAGE WAIT

REJECT OPERATIONEND

NEXT ACTION, ON PREVIOUS RECORD, REJECT OPERATION

AffectedStatements

Example

See Also


�

ON PREVIOUS FORM


��

��

statements ACCELL/4GL statements. See Affected Statements section forstatement restrictions.

ACCELL/Manager executes the ON PREVIOUS FORM section after a previous formrequest. The previous form request can be either explicit or implicit. An explicitprevious form operation occurs when the user presses ��. An implicitprevious form operation occurs when the NEXT ACTION IS PREVIOUS_FORMstatement is executed.

To move to the previous form, ACCELL/Manager executes ON PREVIOUS FORM;then it deactivates the current form. ACCELL/Manager returns to the previous form.On the previous form, ACCELL/Manager resumes execution with the AFTER FORMRETURN section.

If the user presses �� from a zoom form, ACCELL/Manager does notexecute the ON PREVIOUS FORM section. Instead, it executes the AFTER ZOOMsection in the zoom form. ACCELL/Manager resumes execution in the calling formwith the AFTER FORM RETURN section.

You can abort the �� request by using the REJECT OPERATIONstatement in this section.

Use this section to keep an unauthorized user from returning to the previous form, toverify that all required input has been entered, to perform checks on the state of theform, or to save any uncommitted changes made by the user.

Syntax

Arguments

Description


ON PREVIOUS FORM


��

��

��

��

��

��

��

��

��

��

��

AFTER ZOOM, AFTER FORM RETURN, NEXT ACTION, ON NEXT FORM,ON NEXT RECORD, REJECT OPERATION

AffectedStatements

See Also


�

ON PREVIOUS RECORD


��

��

statements ACCELL/4GL statements. See Affected Statements section forstatement restrictions.

ACCELL/Manager executes the ON PREVIOUS RECORD section when it receives arequest to make a previous record in the selected set current. A previous recordbecomes current when one of these events occurs:

The user presses one of the following record commands:��

��

��

The NEXT ACTION statement is executed with one of the following nextactions:NEXT ACTION IS PREVIOUS_RECORDNEXT ACTION IS FIRST_RECORDNEXT ACTION IS PREVIOUS_SET

You can abort the ��, ��, or �� requestby using the REJECT OPERATION statement in this section. To determine which ofthe user commands was executed ON PREVIOUS RECORD, use thelast_command$( ) system function.

ACCELL/Manager executes the ON PREVIOUS RECORD section when the userpresses ��, ��, or ��, even when theselected set has no previous record.

Syntax

Arguments

Description


ON PREVIOUS RECORD


��

��

��

��

��

��

��

��

��

��

��

��

��

��

This script sample checks the state of the current record when the user presses��. If the current record is not stored, the ��

command is rejected. If the current record is stored, ACCELL/Manager makes theprevious record in the selected set the current record.

ON PREVIOUS RECORDIF ( NOT is_current_record_stored$() )THEN

BEGINDISPLAY

’WARNING! The current record has not been updated’ FOR FYI_MESSAGE WAIT

REJECT OPERATIONEND

NEXT ACTION, ON NEXT RECORD, REJECT OPERATION

AffectedStatements

Example

See Also


�

QUEUE COMMAND


��

command_nameA developer-defined command name or an ACCELL/Managerruntime command. A developer-defined command name must bedefined in a DEFINE COMMAND event section. AnACCELL/Manager command must be specified as one of thefollowing strings:

�� !"#$%��&�!$!'#(��)**!$+

,��,

��

��

��

,��,

,��,

��

,��,

��

,��,

��

,��,

��

��

��

��

��

��

��

��

��

�-��

, ��,

��

��

��

��

��

��

�

��

��

��

��

��

��

��

��

��

��

��

��

��

��

��

��

Syntax

Arguments


QUEUE COMMAND

The QUEUE COMMAND statement places a request to execute the specifiedcommand in the pending command queue. The queued command will be executedwhen ACCELL/SQL is about to retrieve user input. Queued commands are executed inthe current context. Usually, the current context is the form associated with the scriptwhere this statement appears.

This statement can be executed within any event section, or from a local or globalfunction.

This statement executes a developer-defined command named mycommand.

QUEUE COMMAND mycommand

This statement executes the ACCELL/Manager �� command.

QUEUE COMMAND ZOOM

BEFORE RECORD, CLEAR COMMAND QUEUE, DEFINE COMMAND, ON EXIT,SET COMMANDlast_command$( ), last_command_name$( )“Creating Script Functions” in ��

Description

AffectedSections

Example

See Also


�

REFRESH SCREEN


��

The REFRESH SCREEN statement forces an immediate update of the information onthe screen by telling ACCELL/Manager to write the output buffers. Writing thesebuffers updates the form to reflect any changes.

ACCELL/Manager buffers output to the terminal. Periodically it updates theinformation on the screen by writing these buffers. Because the output is buffered, asituation can occur where the data or trim to be displayed does not appearimmediately on the screen.

Use the REFRESH SCREEN statement to force ACCELL/Manager to send the outputbuffer to the screen. The REFRESH SCREEN statement forces ACCELL/Manager toupdate the form to reflect any changes.


REPAINT SCREEN

Syntax

Description

AffectedSections

See Also


REJECT OPERATION


��

The REJECT OPERATION statement prevents the user from performing a specificuser operation. The operation rejected depends upon the section where the REJECTOPERATION statement appears.

The table on the next page shows the event sections that can include the REJECTOPERATION statement. For each event section, the table also lists the user operationthat is rejected.

(Note that if you include REJECT OPERATION in the ON EXIT section, the ��

�� command is still executed.)

ACCELL/Manager continues executing any remaining statements in the section afterthe REJECT OPERATION statement completes. In addition, any AFTER section(AFTER ADD, AFTER DELETE, AFTER FIND, AFTER UPDATE) that correspondsto a BEFORE section is also executed.

For example, if REJECT OPERATION is in the BEFORE ADD section,ACCELL/Manager executes all statements in BEFORE ADD and all statements in theAFTER ADD statement as well.

If REJECT OPERATION is in the BEFORE FIND section, ACCELL/Managerexecutes all statements in BEFORE FIND and AFTER FIND but does not execute theON FIND section.

If an AFTER section is not to be executed when a REJECT OPERATION is used inthe BEFORE section, you can use a BOOL “reject flag” and test this “reject flag” inthe AFTER section. If the reject flag is TRUE, the REJECT OPERATION occurredand the AFTER statements are not executed. Otherwise, the AFTER statements areexecuted.

Syntax

Description


�

REJECT OPERATION

Event Section Rejected Operation

BEFORE FIND ��

BEFORE ADD ��

BEFORE UPDATE ��

BEFORE DELETE ��

ON NEXT FORM ��

ON PREVIOUS FORM ��

ON NEXT RECORD ��

��

��

ON PREVIOUS RECORD ��

��

��

ON CLEAR TO FIND ��

ON EXIT ��

This statement is valid only in the following event sections:

��

��

��

��

��

��

��

��

��

��

AffectedSections


REJECT OPERATION

This script sample prevents anyone with a user name other than “Alexander” fromexecuting an add operation. If the user named “Alexander” adds a new row, theAFTER ADD section displays a status message. If some other user tries to add a row,the status message is not displayed even though the AFTER ADD section is executed.

BEFORE ADDSET $valid_add TO TRUEIF ( user_name$() <> ’Alexander’ ) THEN

BEGINREJECT OPERATIONSET $valid_add TO FALSE

END

AFTER ADDIF $valid_add THEN

DISPLAY ’New row added to the Database’FOR FYI_MESSAGE WAIT

BEFORE ADD, BEFORE DELETE, BEFORE FIND, BEFORE UPDATE, ON CLEARTO FIND, ON EXIT, ON NEXT FORM, ON NEXT RECORD, ON PREVIOUS FORM,ON PREVIOUS RECORD

Example

See Also


�

REJECT RECORD

Selection statement

��

The REJECT RECORD statement discards a target table row found during aninteractive find operation.

Within the ON FIND section, you can process each target table row as it is selected.You can use the REJECT RECORD statement to prevent a record from being addedto the selected set. The rejected row does not have a selected set record created andcannot be viewed by the user. If the selected row is not rejected, ACCELL/Managercreates a selected set record for the row.

REJECT RECORD provides a way to limit the records that the user sees after aninteractive find operation. Because the rejected record is never put into the selectedset, the user never sees this record. With this statement, you can provide additionalsecurity constraints that check for specific users or database rows.

When a selected set is created under set consistency, all rows in the selected set areshare locked. If you execute REJECT RECORD to exclude a row from the selectedset, the row is not unlocked, regardless of the RDBMS.

This statement is valid only in an ON FIND section.

This script sample uses the REJECT RECORD statement to prevent the database rowfor “Smithers” from being added to the selected set. Because it is not in the selectedset, this row cannot be selected, viewed, or updated.

ON FINDIF ( emp_last_name = ’Smithers’ ) THEN

REJECT RECORD

AFTER FIND, BEFORE FIND, ON FIND

Syntax

Description

AffectedStatements

Example

See Also


REPAINT SCREEN


��

REPAINT SCREEN restores the entire screen display. All active forms are redrawn,or repainted, on the screen. This statement has the same effect as if the user hadpressed �� .

The statement is useful for restoring the screen display after a call to an externalfunction that has displayed its own screen output.


This script sample defines a command for function key F2. This command displays aspecial form that allows the user to select parameters and to print out a report. Theuser-function display_report_form( ) displays a special form and handles all screeninput. The REPAINT SCREEN statement erases the special report form when thedisplay_report_form( ) function completes and restores what was previouslydisplayed on the screen.

DEFINE COMMAND display_reportKEY IS ‘NONE<KEY>F2’display_report_form()REPAINT SCREEN

REFRESH SCREEN

Syntax

Description

AffectedSections

Example

See Also


�

REPEAT

Control repetition statement

��

statement_list One or more ACCELL/4GL statements. If there is more than onestatement, do not begin and end the statements with the keywordsBEGIN and END.

logical_expressionAny ACCELL/SQL BOOL expression. The expression is evaluated atthe end of each loop iteration. The statement_list is executed untilthis expression becomes TRUE.

The REPEAT statement executes statement_list until logical_expression is TRUE.ACCELL/Manager executes statement_list as long as the logical_expression isFALSE.

To execute the REPEAT statement, ACCELL/Manager first executes statement_list.Next, it evaluates logical_expression to determine whether to reexecutestatement_list. This expression determines the number of times that the statementbody is executed.

When ACCELL/SQL evaluates the logical_expression, it uses 3-way logic. Iflogical_expression evaluates to TRUE, the REPEAT loop exits. If logical_expressionevaluates to FALSE, statement_list is reexecuted. If logical_expression contains anull value, it evaluates to FALSE.

If logical_expression contains a variable, this variable must have an initial valueassigned before the UNTIL clause of the REPEAT statement so that thelogical_expression can be evaluated the first time.

Syntax

Arguments

Description


REPEAT

ACCELL/Manager continues the process of executing the statement_list and testingthe logical_expression until logical_expression is TRUE. When thelogical_expression is TRUE, the REPEAT loop ends.

Because ACCELL/Manager evaluates the logical expression in a REPEAT statementafter each execution of the statement body, the REPEAT statement always executed atleast once.


This REPEAT statement displays the value 100 in the current form field, then thevalues 99, 98, and so on until the value 50 is displayed; the loop is then exited.

SET index TO 100REPEAT

DISPLAY indexSET index TO index – 1

UNTIL index < 50

BREAK, CONTINUE, FOR, WHILE“Using Script Statements” in ��

AffectedSections

Example

See Also


�

RESTART ON FIELD


��

The RESTART ON FIELD statement tells ACCELL/Manager to begin execution of theON FIELD subsection again. RESTART ON FIELD lets the user enter input again byrestarting the ON FIELD section.

You can use the RESTART ON FIELD statement only in the ON FIELD subsection.

When ACCELL/Manager encounters a RESTART ON FIELD statement, itdiscontinues execution of the current ON FIELD subsection. ACCELL/Manager thenreturns to the beginning of the ON FIELD subsection and begins execution.

Any statements in the current section that follow the RESTART ON FIELD statementare not executed after the RESTART ON FIELD statement is executed.

You can test information entered by the user in the ON FIELD section. You use theINPUT statement to tell ACCELL/Manager to stop for user input. If the input is notcorrect, you can require that the user reenter it by including the RESTART ON FIELDstatement in ON FIELD. You can use the DISPLAY statement to display anappropriate error message explaining why the input must be reentered.

This statement is valid only in an ON FIELD section.

Syntax

Description

AffectedSections


RESTART ON FIELD

This script sample receives input from the field sc_name_field. After the user entersa value, the input value is passed to a user function, namechk( ).

FIELD sc_name_field




END

If namechk( ) returns FALSE, the input is not valid. An error message is thendisplayed in the fyi_message system information field, and RESTART ON FIELDrestarts the ON FIELD section.

INPUT, ON FIELD

Example

See Also


�

RESTART TX


��.

form_name The name of the form where execution is to be restarted.

The RESTART TX statement deactivates forms back to the form specified byform_name; form_name itself is not deactivated. If the USING clause is omitted,execution returns to the master application form.

If permitted by the RDBMS, this statement commits the current transaction anddowngrades exclusive locks to shared locks.

To abort the current transaction, you must execute ROLLBACK WORK before theRESTART TX statement.


This statement returns execution to the company form:

RESTART TX USING company;

CHOOSE NEXT FORM�� ! �"��

Syntax

Arguments

Description

AffectedSections

Example

See Also


RETRIEVE

Input statement

�� #��$��-

variable_nameThe name of the variable that is to contain the data retrieved fromstring_expression.

string_expressionThe directory path and file name of the data file from which the datais to be retrieved. The expression can be either a string constant orstring variable.

The RETRIEVE statement reads the contents of BINARY or TEXT files that havebeen stored on disk by the STORE statement. If the file does not exist, or cannot beopened or read, an error results and the variable value is set to UNDEFINED.

If the result is not a STRING expression, or if the result is undefined or null, an errorresults. Use the status$( ) system function to verify the results of the RETRIEVEstatement.


This example retrieves a memorandum contained in the memo file and places it intoa local text variable named $memo.

RETRIEVE TEXT $memo FROM FILE ’memo’

STORE

Syntax

Arguments

Description

AffectedSections

Example

See Also


�

RETURN

Function statement

��/��%��#��%��0��

return_value The value to return to the calling function. This value can be anexpression, a variable or a constant. The value must have the samedata type as the function’s return value, defined in the function’sFUNCTION statement.

The RETURN statement terminates execution of an ACCELL/4GL function. WhenACCELL/Manager reaches the RETURN statement, it evaluates any result parametersand exits from the function.

You can use this statement anywhere within an ACCELL/4GL function. You caninclude more than one RETURN statement in a single function.

For functions that do not return values, the use of the RETURN statement in thefunction body is optional. If control passes to the end of the function body withoutencountering a RETURN statement, ACCELL/Manager performs the RETURNstatement automatically and does not return a value.

For functions that do return values, you must use this statement to return the value.To return values, include the return value within parentheses after the RETURNkeyword. If control passes to the end of the function body without encountering aRETURN statement, ACCELL/Manager returns an undefined value.

Make sure that the data type of the value being returned matches the function’s returnvalue defined in the FUNCTION statement.

This statement is valid only in a FUNCTION section.

Syntax

Arguments

Description

AffectedSections


RETURN

This script sample defines a local function called get_netpay( ). This local functionuses the RETURN statement to return the AMOUNT value of net_salary.

LOCAL AMOUNT FUNCTION get_netpay (gross_salary, RESULT taxes)

LOCAL the_taxrate, net_pay

BEGINSET the_taxrate TO

SELECT tax_rate FROM ratesWHERE lower_sal <= $gross_salary AND upper_sal >= $gross_salary

SET taxes TO (gross_salary * the_taxrate)SET net_salary TO gross_salary – taxesRETURN (net_salary)

END

FUNCTION

Example

See Also


�

REVOKE


��

��

��

��

�� 1��

��%��

�� &��2��$��&��2��$�� %��

��.


column_name The name of a table column.


user_name The database user’s name.

The REVOKE statement drops (removes) user privileges.



Syntax

Support

Arguments

Description


REVOKE


This REVOKE statement drops SELECT privileges on the emp_salary column of theemp_table from all PUBLIC users.

REVOKE SELECT (emp_salary) ON TABLE emp_table FROM PUBLIC;

GRANT�� ! �"��Documentation provided by the RDBMS vendor

AffectedSections

Example

See Also


�

ROLLBACK WORK


��

��



or



The ROLLBACK WORK statement tells the database to abort the current transactionand begin a new one. The RDBMS handles backing out all uncommitted databaseoperations, interactive and noninteractive, in the current transaction.

Transaction rollback is possible only if the database has transaction logging.

When the current transaction is aborted, the following events occur:

all current locks are released

all uncommitted update, delete, and insert operations are undone.

The user does not see any changes on the screen when ROLLBACK WORK isexecuted. The current form is still displayed along with any data on the form.

If the aborted transaction contains a selected set, all records in the selected set nolonger have locks, even if the records still display on the form.

Syntax

Arguments

Description


If the form uses the Browse feature, the current selected set may have been only asubset of all matching records. In this case, the full selected set is lost when thetransaction aborts. The user cannot use �� or �� to see additionalsubsets of the selected set.

To regain the locked selected set, use NEXT ACTION IS CLEAR TO FIND to clearthe form. If necessary you can recreate the selected set with NEXT ACTION IS FIND.

After the transaction is aborted, ACCELL/Manager continues to execute anyACCELL/4GL statements that follow the ROLLBACK WORK statement within theevent section.



�

ROLLBACK WORK

This statement is invalid in the ON FIND section and the EXECUTING clause.

This example attempts an INSERT after the user inputs the form field doinsert. If thedatabase insert fails, the transaction is aborted and execution returns to the previousform.

FIELD doinsertAFTER FIELD

INSERT INTO stock (st_number, st_description, st_unit_price) VALUES ($snum, $sdesc, $price);IF (status$() <> SS_NORM) THEN

BEGINROLLBACK WORKNEXT ACTION IS PREVIOUS FORM

END

BEGIN WORK, COMMIT WORK, UNLOCKtx_mode$( )

AffectedSections

Example

See Also


SELECT


��

��

��

��

��

��

��

��

This statement must conform to the syntax specified by the RDBMS. In addition, seethe restrictions for INFORMIX and ORACLE described below.

db_column_list A list of columns in table_name separated by commas. This listcontains the columns that are obtained from the selected databaserow. Column names can be specified as column names, * (allcolumns), or as an expression.


table_name A list of database tables containing rows to be selected.

logical_expressionAn RDBMS Boolean expression that is evaluated to determine whichrows in the table to select.

sort_db_column_listA list of columns from db_column_list, separated by commas. Thislist specifies the order in which to sort the selected database rows.Numbers corresponding to the position of column names indb_column_name can be used instead of column names. Eachcolumn name can be followed by one of the keywords ASC(ascending) or DESC (descending). If not specified, ASC is thedefault sorting order.

Syntax

Support

Arguments


�

SELECT

EXECUTING_clauseAn ACCELL/4GL EXECUTING clause. This clause is executed foreach selected database row. Without an EXECUTING clause, thestatement selects only the first row that matches the specified searchcriteria and stops; any other matching rows are not selected.

The SELECT statement initiates a noninteractive find operation to retrieve a rowfrom a specified database table or tables, table_name.

ACCELL/SQL variables can be used in the selection list but must be prefixed by adollar sign ($) and used as part of an expression.

The set of rows to be selected is determined by the WHERE clause. As the RDBMSsearches the tables, the logical_expression for each row is evaluated and the value isreturned. If the logical_expression evaluates to TRUE for a row, SELECT selects therow. If the logical_expression evaluates to FALSE or to a null value, the row is notselected.

In the WHERE clause of a SELECT statement, if an expression compares a databasecolumn value with a value, make sure that the database column name is the firstoperand, as shown here:

database_column = value

If the SELECT includes a locking clause, this locking clause determines the lockstatus of the selected rows. This clause can have one of two keywords: XLOCK orSLOCK. The XLOCK clause requests that all selected rows have an exclusive lock.The SLOCK clause requests that all selected rows have a shared lock. If the lockingclause is omitted, the selected rows are not locked. SELECT selects exclusive-lockedrows only if the application RDBMS allows dirty data to be read.

If the WHERE clause is omitted, the first row in the table is selected. To select alltable rows, you must include an EXECUTING clause with SELECT.

The EXECUTING clause tells ACCELL/Manager to select all matching rows. If theSELECT statement also contains a WHERE clause, all rows that meet the conditionsin the logical_expression are selected.

Description


SELECT

The ORDER BY clause tells ACCELL/Manager to select database rows in the sortorder determined by the sort_db_column_list. Each item in sort_db_column_list isthe name of a column on which to sort.

In the ordered column list, you specify the column names in the priority the columnvalues are to be sorted. Selected rows are sorted by the values of the first column inthe ordered column list. If two rows have the same value for the first column, thesetwo rows are sorted by the values of the second column in the ordered column list,and so on.

You must specify whether you want the column values sorted in ascending ordescending order. To specify a sort order for each column in the ordered column list:

include one of the keywords ASC or DESC after the column name

include a string expression that evaluates to either ASC or DESC.

Use the ACCELL/SQL status$( ) system function to test the success of a SELECTstatement.

Additional HelpFor more information about dirty data, see “Controlling ACCELL/SQL Transactions”in �� !"�#�$��% ��!��.

��


��



The ROLLBACK WORK statement is invalid in a SELECT statement block.

AffectedSections

AffectedStatements


�

SELECT

This SELECT statement selects the first row in the employee table. Theemp_last_name value is then assigned to the ACCELL/SQL variable one_name.

SET one_name TOSELECT employee.emp_last_name FROM employee;

DELETE, DELETE CURRENT RECORD, DELETE SELECTED ROW,EXECUTING, GRANT, INSERT, SET, SLOCK, UPDATE, XLOCK�� !"�#�&'()!�� Documentation provided by the RDBMS vendor

Example

See Also


SET

Assignment statement RDBMS dependent

* �� +��

� +�� !�� ,�+��*��

The row valued function call is supported for SYBASE SQL Server only.

form_name The name of a screen form.

variable Any valid ACCELL/SQL variable, including an array element or anentire array. The variable is set to the value of the expression. Theexpression and the variable must be type compatible.

attribute Any valid ACCELL/SQL variable attribute name except function keyattributes. The attribute will be set to the value of the expression.The expression and the attribute must be type compatible. TheCLEAR_ADD_EXP and CLEAR_FIND_EXP attributes cannot beinitialized by a SELECT statement.

expression Any valid ACCELL/SQL expression. The SET statement assignsexpression to the variable or attribute.

variable_list One or more ACCELL/SQL variable names, separated by commas.Each variable is assigned the value of the corresponding column inthe SELECT_statement.

(INFORMIX and SYBASE SQL Server only) When setting targetvariables, field variables, and target field variables to values returnedby a ROW_VALUED stored procedure call, the data type of eachvariable must be compatible with the data type of the correspondingdatabase column. For general variables, the variables take the typesof the values returned by the stored procedure call.

Syntax

Support

Arguments


�

SET

SELECT_statementAny valid SQL SELECT statement. The SELECT statement caninclude locking clauses and an EXECUTING block.

row_valued_function_call(INFORMIX and SYBASE SQL Server only) The name of aROW_VALUED stored procedure, in the following format:

function_name([parameter_list])

The function_name must be the name of a stored procedure that isdeclared as ROW_VALUED.

The parameter_list is one or more input parameters, separated bycommas, that are passed to the stored procedure. If a default valuefor an input parameter has been specified in the stored proceduredefinition, you can indicate that you want to use the default value byreplacing the parameter name with the keyword UNDEFINED:

function_name(UNDEFINED)

The SET statement is the ACCELL/4GL assignment statement. This statement can setvariables of all ACCELL/SQL data types. It can also set the ACCELL/SQL variableand form attributes.

The SET statement does not set command attributes. To set command attributes, usethe SET COMMAND statement.

If variable is a field variable, the displayed value changes when the variable’s valuechanges. If the variable’s form field is on a covered active form, the new field valueappears when the form reappears. If variable is a target variable, the new targetcolumn value is not added to the database until the current record is added orupdated.

Description


SET

If variable is a general variable, the variable’s data type is determined when youassign the first value to the variable. To change the data type of a general variable,you must first set the variable to UNDEFINED and then assign the value of the newdata type. You cannot assign the NULL constant to an undefined general variable.

If the SELECT statement finds no matching database rows, the value of variable isset to UNDEFINED.

You cannot change the data type of a field, target, or target field variable.

The SET statement is not only a statement, it is also an expression. Unlike mostACCELL/4GL statements, the SET statement has a value. The value of the SETexpression is the value of variable or attribute. You can use the SET statementwherever an ACCELL/SQL expression is valid.

The SET statement cannot be used in a database SQL statement.

WarningBecause the SET statement is also an expression, make sure that the placementof SET within your statements is unambiguous. Do not use the SET statementafter a statement that ends with an optional expression unless you terminate theprevious statement with a semicolon (;).

In most statements, the use of a semicolon (;) is optional. However, it is required inthis case to distinguish the statements. If the previous statement is not terminated, theSET statement is interpreted as an expression that belongs to the previous statement.

��

�� !�

For INFORMIX or SYBASE SQL Server, a ROW_VALUED stored procedure cancontain one or more SELECT statements.



�

SET

The following paragraphs show examples of some of the ways you can use the SETstatement to set variables, attributes, expressions, and so on.

Selecting Variable Values

This SET statement selects the first row in the employee table. The emp_last_namevalue is then assigned to the ACCELL/SQL variable one_name.

SET one_name TOSELECT employee.emp_last_name FROM employee

The next example shows how to display the current form field’s value and then selectthe first name from employee where last_name is “Smith” and assign it to var1.You must end the DISPLAY statement with the statement terminator.

DISPLAY;SET var1 TO

SELECT emp_first_name FROM employeeWHERE emp_last_name = ’Smith’

Setting Variable Attributes

The next SET statement sets the UPDATEABLE field attribute of the field variablescreen_field to FALSE. Setting the UPDATEABLE field attribute to FALSE meansthat the user cannot edit the field’s value.

SET screen_field:UPDATEABLE TO FALSE

Setting Clear-to-Find Expressions

To set the initial search criteria for the NUMERIC target field variable inumber (onthe form inventory) to inventory numbers in the range 100 to 500 (inclusive):

SET inventory:inumber:CLEAR_FIND_EXP TO 100 => 500

Example


SET

To set the initial search criteria for the AMOUNT target field variable price (on theform inventory) to all prices greater than $25,525.50:

SET inventory:price:CLEAR_FIND_EXP TO 25,525.50 =>

To set the initial search criteria for the NUMERIC target field variable count (on theform inventory) to inventory items with counts less than ten (10):

SET inventory:count:CLEAR_FIND_EXP TO => 10

To set the initial search criteria for the NUMERIC target field variable location (onthe form inventory) to the location code of the current warehouse:

SET inventory:location:CLEAR_FIND_EXP TO $warehouse

To set the initial search criteria for the STRING target field variable manufacturer(on the form inventory) to “Acme Inc*”:

SET inventory:manufacturer:CLEAR_FIND_EXP TO ’Acme Inc*’

The asterisk in the search criteria specifies a search for all versions of the Acmemanufacturer (Acme Inc;, Acme Incorporated; Acme Inc) during the target tablesearch.

To set the initial search criteria for the NUMERIC target field variable location (onthe form inventory) to all location codes greater than or equal to the currentwarehouse code:

SET inventory:location:CLEAR_FIND_EXP TO $warehouse =>


�

SET

Setting Clear-to-Add Expressions

The following examples show a variety of ways to use clear-to-add expressions.

To set the initial value for the NUMERIC target field variable order_time (on theinventory form) to 4 weeks:

SET inventory:order_time:CLEAR_ADD_EXP TO 4

To set the initial value for the NUMERIC target field variable location (on theinventory form) to the location code to indicate the current warehouse:

SET inventory:location:CLEAR_ADD_EXP TO $warehouse

Setting Variables With System Functions

The next SET statement assigns the null value to the NUMERIC variable total.Because assigning the NULL constant to an undefined general variable is not valid,this SET statement converts the NULL constant to a NUMERIC null value with theto_num$( ) type-conversion function.

SET total TO to_num$(NULL)

Setting Array Values

This example sets the initial value of an array cell:

SET array2[5]:CLEAR_ADD_EXP TO $base + 5

This example sets the initial value of each cell of an array to 0:

SET array2:CLEAR_ADD_EXP TO 0


SET

The next SET statement assigns the value TRUE to the BOOL variable valid_add.

SET valid_add TO TRUE

The next SET statement assigns the value 0 to the three variables, var1, var2, andvar3.

SET var1 TO SET var2 TO SET var3 TO 0

Using SET With Control Statements

The next example adds 100 database rows to the table stock. The SET statementassigns the initial value and the reinitialized value to the FOR loop’s control variable,index.

FOR (SET $index TO 1; $index <= 100; SET $index TO $index + 1)INSERT INTO stock

st_number: $index

Using a Stored Procedure

The following example calls the emp_info( ) stored procedure to select informationfrom the employee table for the employee having the employee number specified inemp_num:

��

��

��

��

SET $dept, $lname, $fname, $title TO emp_info($emp_num)

CREATE PROC emp_info @emp_num intAS SELECT dept, lastname, firstname, title

FROM employee WHERE emp_num = @emp_num

SYBASE SQLServer


�

SET

The following example shows a call to a stored procedure named sp_calc( ), in whichdefault input parameter values are defined. If either of the input parameters passedfrom ACCELL/SQL to the stored procedure is UNDEFINED, sp_calc( ) uses thedefault value defined in the stored procedure definition.

. . .INPUT

IF ($nbr2 < 0) THEN SET $Num1, $Num2 TO sp_calc (18, UNDEFINED) EXECUTING . . .

CREATE PROC sp_calc @nbr1 int = 10 @nbr2 int = 20

AS . . .

��

��!��

��

�� "��#$��

ADD_ALLOWED, CLEAR_ADD_EXP attributesEXTERN, SET COMMANDsp_compute$( ), sp_return$( ), sp_select$( )“Attributes Summary” chapter of this manual�� !"�#�$��% ��!�� !"�#�&'()!��

See Also


SET COMMAND

Assignment statement User-interface dependent

� �� "�� "��

��

��"�� "�� #�$%�&��'(�#�� #� ��*��&��'(-�.�.�#

The KEYS TO ’modifier<Key>keysym’ clause is supported for graphical userinterfaces only.

command_nameName of either an ACCELL/Manager runtime command or adeveloper-defined user command.

When a command name consists of more than one word, the wordsin the name are joined by an underscore (_). The command name isnot case sensitive: you can enter the name in either uppercase orlowercase letters. The following commands are valid arguments:

'�+�� /��*�� "��")��"��"��"��"��"��"��"��

��"��"��"��"��"��"��"��"��"��"��"��"��"��)��

Syntax

Support

Arguments


�

SET COMMAND

Developer-defined commands apply to the current form only. Thesecommands include non-�� executables, such as operatingsystem commands. To avoid potential conflicts with reserved words,you can enclose command names within a pair of quotation marks(”).

ACTION Activates the command in both find mode and add/update/deletemode. The ACTION attribute cannot be used in combination witheither of the AUD_ACTION and FIND_ACTION attributes.Assigning an enable_string to ACTION overrides the settings ofboth the AUD_ACTION and FIND_ACTION attributes.

AUD_ACTION Activates the command in add/update/delete mode only. TheAUD_ACTION and FIND_ACTION attributes can be used alone or incombination.

FIND_ACTION Activates the command in find mode only. The AUD_ACTION andFIND_ACTION attributes can be used alone or in combination.

enable_string Action specifier assigned to the action attribute. The enable_stringdetermines the response of ACCELL/Manager when the user pressesthe function key. The enable_string can be either of two values:

’ENABLED’ (Default) The function key is enabled and thecommand label is displayed in the function keyprompt system field.

’DISABLED’ No label is displayed in the prompt area; a bell(beep) character is sent to the terminal if the userpresses the key. No event sections or statements areexecuted. If a function key action is set toDISABLED, no function key prompt is displayed,regardless of the label attribute settings. However,disabling a command does not affect or preventexecution of the command by a NEXT ACTIONstatement.


SET COMMAND

By setting the AUD_ACTION attribute toDISABLED, you disable the function key inadd/update/delete mode. By setting theFIND_ACTION attribute to DISABLED, you disablethe function key in find mode.

You can set the function key action to DISABLED inboth form modes by setting the ACTION attribute toDISABLED. Assigning the DISABLED value toACTION overrides the settings of both theAUD_ACTION and FIND_ACTION attributes.

LABEL Defines the function key prompt for both find mode andadd/update/delete mode. The LABEL attribute cannot be used incombination with either of the AUD_LABEL and FIND_LABELattributes. Assigning a string_expr to LABEL overrides the settingsof the AUD_LABEL and FIND_LABEL attributes.

If a function key action is set to DISABLED, no function key promptis displayed, regardless of the LABEL setting.

AUD_LABEL Defines the prompt that appears when the form is inadd/update/delete mode. The AUD_LABEL and FIND_LABELattributes can be used alone or in combination.

If a function key action is set to DISABLED, no function key promptis displayed, regardless of the AUD_LABEL setting

FIND_LABEL Defines the prompt that appears when the form is in find mode. TheAUD_LABEL and FIND_LABEL attributes can be used alone or incombination.

If a function key action is set to DISABLED, no function key promptis displayed, regardless of the FIND_LABEL setting

string_expr String expression to be used as the label for the command. The labelappears in the function key prompt system field. If not explicitlyspecified, the default label is the name of the command as specifiedin the unicap file.


�

SET COMMAND

’None<Key>Fnn’

Fnn is a function key name, such as F4 or F11. The key expressionis case sensitive and must be entered exactly. For example, to specifyfunction key �� , you use the following string:

’None<Key>F5’

modifier<Key>keysym(Graphical user interfaces only) Specifies a key event.

modifier specifies an event modifier key, for example:

Alt Mod1 Button1 HyperCtrl Mod2 Button2 SuperLock Mod3 Button3 NoneMeta Mod4 Button4 AnyShift Mod5 Button5

Event modifier key names are dependent upon the syntax required byyour graphical user interface.

keysym is an X11 keysym name, as found in the keysymdef.h file.By default, the key sequence overwrites similar existing keysequences for the command.

The SET COMMAND statement specifies or changes the attributes ofdeveloper-defined user commands and ACCELL/Manager commands. The commandattributes affect whether the command is enabled or disabled, the function keyassigned to the command, and the effect of a command in find mode oradd/update/delete mode.

By default, ACCELL/Manager command attributes are defined and in effect only forthe form where they are set. To change the scope of ACCELL/Manager commands,use the CMDSCOPE configuration variable.

Developer-defined commands must first be defined by the DEFINE COMMANDevent section and by default are in effect only when the form on which they aredefined is active. To control the scope of commands, use the CMDSCOPEconfiguration variable.

Description


SET COMMAND

� *+,-.*/ �0� �%1� 2*.�0

For graphical user interfaces only, you can specify command key events.

When a command action is ’ENABLED’, the command label is displayed in asensitive button on the User pull-down menu. Users can execute the command eitherby selecting the command button or by pressing the command key sequence. When acommand action is ’DISABLED’, the command label is displayed as an insensitive(stippled or gray-shaded) button on the User pull-down menu. Users cannot executethe command.

If no command label is specified in the SET COMMAND statement, the default labelis taken from the resource file. If the command label is not specified in the SETCOMMAND statement or in the resource file, the default label is the name of thecommand.

A command event modifier can specify combinations or limitations, for example:

None No modifiers are allowed.Any Any or no modifier is allowed.Mod1 Mod2 Both Mod1 and Mod2 are required; other modifiers are also

allowed.!Mod1 Mod2 Only Mod1 or Mod2 are allowed; other modifiers are

prohibited.Mod1 ~Mod2 Mod1 is required; all other modifiers except Mod2 are allowed.

A modifier is optional. For complete information about modifiers, see the X11translation table syntax specified for your graphical user interface.

Keys can be specified by the keysym name or value specified in the keysymdef.hfile. Some translations may require the keysym value if symbolic names are notproperly interpreted. The keysym name is case sensitive and must be entered exactlyas specified in the translation table (remove the XK_ prefix).

Command Actions

Command Labels

Command Keys


�

SET COMMAND


The following examples show how to use the SET COMMAND statement.

FIELD memosBEFORE FIELD

SET COMMAND mail : ACTION TO ’DISABLED’ ;...SET COMMAND CLEAR_ADD : KEYS TO ’None<Key>F7’ ;

SET COMMAND UPDATE:ACTION TO ’DISABLED’ ;

SET $find_key TO ’None<Key>F8’ ; SET COMMAND FIND:KEYS TO $find_key ;

The following example shows an example of using the SET COMMAND statementto specify a command key event.

FIELD memosBEFORE FIELD

SET COMMAND mail : ACTION TO ’DISABLED’ ;...SET COMMAND CLEAR_ADD : KEYS TO ’Ctrl<Key>C’ ;

ACTION, AUD_ACTION, AUD_LABEL, FIND_ACTION, FIND_LABEL, LABELattributesCLEAR COMMAND QUEUE, DEFINE COMMAND, QUEUE COMMAND, SETCMDSCOPE in �� !"�#�� *�� 0��.�&�*�� !"�#�'�+�� * ��*��“Defining User Commands” in �� !"�#�$��% ��!��

AffectedSections

Example

GraphicalUser

Interface

See Also


SLOCK

ACCELL/4GL database locking statement RDBMS dependent

��

INFORMIX Supported with the restrictions described below.

INGRES Supported as described.

ORACLE Supported with the restrictions described below.

SYBASE SQLServer

Supported as described.

Unify DataServerSupported as described.


table_name The name of the database table to be shared-locked or of the tablecontaining the rows to be shared-locked.

logical_expressionAn RDBMS Boolean expression. The expression is evaluated todetermine which database rows are issued a shared lock request.

An SLOCK statement issues a shared-lock request on a database object. This objectcan be either a table or a set of database rows. A shared lock allows a transaction toread an object with the assurance that another transaction cannot update it while thelock is held on that object. When a table or row has a shared lock, the transaction canread the locked object, but it cannot modify it. Other transactions can obtain readaccess on the locked object.

You need not use locking statements when selecting records with the SELECTstatement.

Syntax

Support

Arguments

Description


�

SLOCK

Use ACCELL/SQL locking statements (SLOCK, XLOCK, UNLOCK) in a multiuserapplication to protect selected rows and tables from modification. A transaction hasread access on any object it has shared-locked and both read and write access on anyobject it has exclusive-locked.

An object can be read without being locked.

Using the WHERE Clause

The set of rows for which to issue the lock request is determined by the WHEREclause. SLOCK requests a shared lock for all rows that satisfy the logical_expressionin the WHERE clause. This logical_expression must include a test on at least onecolumn name from the table table_name.

If the logical_expression evaluates to TRUE for a selected row, SLOCK issues ashared lock request for the row. If the logical_expression evaluates to FALSE or to anull value for a selected row, SLOCK does not issue a shared-lock request for therow.

If the WHERE clause is omitted, SLOCK requests a shared lock on the entire table,table_name.

��

For INFORMIX, the WHERE clause cannot include a column having the TEXT orBYTE data type.

��


Controlling Locks

Execution of an SLOCK statement does not guarantee that the specified row or tableis shared-locked. The statement generates a request for a shared lock on the object. Ifthe request cannot be granted, another transaction is probably holding a conflictinglock.


SLOCK

Use the ACCELL/SQL system function status$( ) to test the success of an SLOCKstatement. Any time an SLOCK requests a shared lock on a set of rows, the lockrequest fails if any one of the rows cannot be locked. In this case, the status$( )system function returns an SS_LMOUT status code.

You can write your application so that it attempts a lock several times if an SLOCKfails. If, after repeated attempts, the SLOCK request still fails, it is best to restart thetransaction and release all locks.

To release a shared lock, use the UNLOCK statement or start a new transaction ateither the Start Tx or Restart Tx transaction level. You can use the CHOOSE NEXTFORM or CHOOSE FIRST FORM statements to specify the transaction level.


This SLOCK statement requests a lock on the entire table employee:

SLOCK employee ;

This SLOCK statement requests a lock on the rows in the employee table with a jobcode of “REP”.

SLOCK employee WHERE emp_job_code = ’REP’ ;

CHOOSE FIRST FORM, CHOOSE NEXT FORM, COMMIT WORK, EXECUTING,SELECT, SET, UNLOCK, XLOCKstatus$( )�� !"�#�&'()!��

AffectedSections

Example

See Also


�

STORE

Output statement

�� *��

expression The expression must be a BINARY or TEXT expression. If theexpression is of any other type or if the expression is undefined, anerror results.

string_expressionThe directory path and file name of the file that contains the storedtext or binary value. The expression can be either a string constant ora string variable.

file_mode The file mode determines how the file will be opened. If specified,file mode must be one of the following keywords:

CREATE (Default) If the file already exists, an error results. Ifthe file does not exist, it is created.

OVERWRITE If the file exists, it is overwritten. If the file does notexist, it is created.

APPEND If the file exists, data is appended at the end of thefile. If the file does not exist, it is created.

The STORE statement allows you to write TEXT or BINARY values to disk. If thestorage file cannot be written or created, an error results.


Syntax

Arguments

Description

AffectedSections


STORE

This statement stores the contents of the text field description to the file specified bythe string variable $copy_file.

FIELD description...AFTER FIELD

IF ($save_copy=TRUE) THENSTORE description TO FILE $copy_file

RETRIEVE

Example

See Also


�

SWITCH

Control decision statement

��

��

��1��

��

��

��

expression Any valid ACCELL/SQL expression. The expression is evaluated todetermine the CASE clauses to be executed. The expression and theconstant must be type compatible.

constant A valid ACCELL/SQL constant. The constant can be of any of thevalid ACCELL/SQL types: NUMERIC, FLOAT, AMOUNT, BOOL,STRING, TEXT, BINARY, DATE, or TIME. It can also be the NULLconstant. The constant must be type compatible with the expression.

statement_list One or more ACCELL/4GL statements.

The SWITCH statement conditionally executes one of the several statement_lists.Each statement_list is introduced by either a CASE clause or a DEFAULT clause.

To execute the SWITCH statement, ACCELL/Manager first evaluates expression andcompares this value to all the constant values in the CASE clauses. Each CASEconstant must be unique. The constant value can be the NULL constant (CASENULL:) to compare a null value. If the expression value matches one of the CASEconstants, ACCELL/Manager executes the corresponding statement_list.

Syntax

Arguments

Description


SWITCH

If expression evaluates to a BOOL value, the three possible values are TRUE,FALSE, and UNKNOWN. If the control expression contains a null value, it evaluatesto UNKNOWN and ACCELL/SQL executes the CASE NULL clause.

If you omit the CASE NULL clause and the control expression evaluates to a nullvalue, the DEFAULT clause is executed, if this DEFAULT clause exists.

If there are no matching CASE constants, ACCELL/Manager executes thestatement_list that follows the DEFAULT clause, if this clause exists. If theDEFAULT clause does not exist, ACCELL/Manager just skips to the next statement.

The DEFAULT clause is optional in a SWITCH statement, and a SWITCH statementcan contain only one DEFAULT clause. The DEFAULT clause can appear anywherein the body of the SWITCH statement.

WarningDo not make any assumptions about the order in which the SWITCH expressionand CASE constants are compared. There is no fixed comparison order.

When you want to use a single statement list for more than one CASE value, you canuse more than one CASE clause at the beginning of the statement list. This SWITCHstatement has the following form:

SWITCH expression BEGIN ...

CASE constant: CASE constant:

statement_list END



�

SWITCH

This SWITCH statement tests an abbreviated shipping code (ship_code) and sets thevariable exp_ship_code to an appropriate expanded shipping code. If ship_code hasa null value, the shipping code is initialized to “None”. If ship_code has a valueother than U, P, A, or the null value, the DEFAULT clause is executed andexp_ship_code is set to “Unspecified”.

SWITCH ship_code BEGIN

CASE ’U’:SET exp_ship_code TO ’UPS’

CASE ’P’:SET exp_ship_code TO ’Parcel Post’

CASE ’A’:SET exp_ship_code TO ’Air Express’

CASE NULL:SET exp_ship_code TO ’None’

DEFAULT:SET exp_ship_code TO ’Unspecified’

END

IF“Using Script Statements” in �� !"�#�$��% ��!��

Example

See Also


UNLOCK


��

INFORMIX The UNLOCK statement is not supported for INFORMIX.

INGRES The UNLOCK statement is not supported for INGRES.

ORACLE The UNLOCK statement is not supported for ORACLE.

SYBASE SQLServer

The UNLOCK statement is not supported for SYBASESQL Server.

Unify DataServerSupported.


table_name The name of the database table to be unlocked or of the tablecontaining the rows to be unlocked.

logical_expressionAny ACCELL/SQL Boolean expression. The expression is evaluatedto determine which database rows to unlock.

The UNLOCK statement attempts to release a shared lock held by the currenttransaction on a database object. This object can be either a table or a set of databaserows. Exclusive locks are not affected by this statement.

The COMMIT WORK statement and the Restart Tx transaction level downgradeexclusive locks to shared locks. After the exclusive lock has been downgraded, youcan release the shared lock with the UNLOCK statement.

Syntax

Support

Arguments

Description


�

UNLOCK

The Start Tx transaction level releases all locks held by the current transaction beforeit starts a new transaction. Using Start Tx is the only way to directly release anexclusive lock. You can use the CHOOSE FIRST FORM and CHOOSE NEXTFORM statements to specify a transaction level.

The set of rows for which to issue the lock release is determined by the WHEREclause. UNLOCK requests a lock release for all shared-lock rows that satisfy thelogical_expression in the WHERE clause. This logical_expression must include atest on at least one column name from the table table_name.

If the logical_expression evaluates to TRUE for a selected row, UNLOCK issues alock release request for the row. If the logical_expression evaluates to FALSE or to anull value for a selected row, UNLOCK does not issue a lock release request for therow.

If the WHERE clause is omitted, UNLOCK requests a lock release on the entireshared-locked table, table_name.

Unlocking rows that are already unlocked is not an error. It is good programmingpractice to unlock any rows or tables no longer required. After the object is unlocked,other users and applications can access it.


Use the UNLOCK statement to unlock rows and tables locked by previous statementsin the current transaction.

If the RDBMS does not provide a method for unlocking rows, the UNLOCKstatement has no effect.



UNLOCK

This UNLOCK statement unlocks the entire table employee. All shared-lock rows inemployee owned by your transaction are unlocked. Exclusive-locked rows remainexclusive-locked.

UNLOCK employee ;

This UNLOCK statement unlocks the rows in the employee table that have anemployee job code (emp_job_code) equal to “REP”. The COMMIT WORKstatement before the UNLOCK statement downgrades the exclusive locks held by thecurrent transaction to shared locks.

COMMIT WORKUNLOCK employee

WHERE emp_job_code = ’REP’ ;

CHOOSE FIRST FORM, CHOOSE NEXT FORM, COMMIT WORK, ROLLBACKWORK, SLOCK, XLOCK�� !"�#�&'()!��

Example

See Also


�

UPDATE


�� 3 ��

��

This statement must conform to the syntax specified by the RDBMS. In addition, seethe restrictions for INFORMIX, INFGRES, and ORACLE described below.


table_name The name of the table containing the rows to be updated. Thetable_name can also take the form schema.table_name.

db_column A column to be updated.

expression An expression. Each expression is evaluated, and the resulting valueis assigned to the corresponding table column.

logical_expressionAn RDBMS Boolean expression. The expression is evaluated todetermine which rows in the database table to update.

The UPDATE statement initiates a noninteractive update operation to update a row orrows from a specified database table, table_name.

When ACCELL/Manager encounters this statement, it prepares the statement forprocessing by the database. Because this statement is executed by the RDBMS, itmust conform to the syntax requirements of the RDBMS; extensions provided by theRDBMS can also be included.

Syntax

Support

Arguments

Description


UPDATE

This statement updates column values by assigning the value in expression to thecolumn db_column.

The set of rows to update is determined by the WHERE clause. The UPDATEstatement updates all rows that satisfy the logical_expression in the WHERE clause.This logical_expression must include a test on at least one column name from thetable table_name.

As table_name is searched, the logical_expression for each row is evaluated. If thelogical_expression evaluates to TRUE for a row, the row is selected for updating. Ifthe logical_expression evaluates to FALSE or to a null value, the row remainsunchanged.

Before updating a row, an exclusive lock is obtained.

If UPDATE encounters a locked row or some other error condition, the updateoperation on the row fails, the UPDATE statement terminates, and no rows areupdated.

If the WHERE clause is omitted, UPDATE attempts to update all rows in thespecified table. These rows are updated if no error is encountered (such as a lockedrow) during the update operation.

Use the ACCELL/SQL system function status$( ) to test the success of a databaseupdate. If the user does not have update privilege, the status$( ) function returns astatus code of SS_WRACS after an update operation. If the record to be updated is notfound, status$( ) returns SS_NOREC.

WarningUsing a noninteractive database statement to update rows that have records inthe form’s selected set does not update the selected set records. The selected setrecords remain unaffected by the update although their associated rows have beenupdated.

If the UPDATE statement cannot obtain an exclusive lock on the selected row or ifany other error occurs, the update operation fails, the statement terminates, and norows are updated.


�

UPDATE

��


��

You can use the UPDATE statement to update columns of one table by using columnsfrom another table or tables, if you use this form of the update statement:

UPDATE table_name [FROM table_name [, table_name] * ] SET . . .

��


�%-2' �*1*�� !�

The maximum number of updated columns is set by the configuration variableSQLFLDCNT.


This UPDATE statement retrieves each row in the employee table that has a job codeof “REP”. As each row is read, the department code column (emp_department) isupdated with “SALES” and the row is then written back to the employee table. If thenoninteractive update operation fails, this code notifies the user and rolls back thecurrent transaction.

UPDATE employeeSET emp_department = ’SALES’ WHERE emp_job_code = ’REP’ ;

IF ( status$() <> SS_NORM ) THENBEGIN

ROLLBACK WORKDISPLAY ’Update failed; aborting tx’


AffectedSections

Example


UPDATE

DELETE, DELETE CURRENT RECORD, DELETE SELECTED ROW, GRANT,INSERT, SELECT, UPDATE CURRENT RECORD�� !"�#�&'()!�� Documentation provided by the RDBMS vendor

See Also


�

UPDATE CURRENT RECORD

Update statement

��

The UPDATE CURRENT RECORD statement initiates an add or update operation onthe current record. If the current record is not yet in the selected set, UPDATECURRENT RECORD performs an interactive add operation to add a new record tothe selected set and insert a new row in the target table. If the current record alreadyexists in the selected set, UPDATE CURRENT RECORD performs an interactiveupdate operation to update the form’s current record and the associated target tablerow.

When used in the ON FIND section, UPDATE CURRENT RECORD updates thecurrent record in the target table and stores the updated record in the selected set.

The current record remains current after the target table row is inserted or updated.

UPDATE CURRENT RECORD does not cause the execution of any add or updatesections (BEFORE ADD, AFTER ADD, BEFORE UPDATE or AFTER UPDATE).

This statement requests an exclusive lock on the current record’s target table row. Ifthis exclusive lock request is successful, UPDATE CURRENT RECORD performs theinteractive update operation. To test the success of an UPDATE CURRENT RECORDstatement, use the system function status$( ) in the same section that contains theUPDATE CURRENT RECORD statement.

If UPDATE CURRENT RECORD is used on a form that does not have a target table,it updates only the current record in the selected set.

If an exclusive lock cannot be obtained, an error message is displayed, and status$( )returns a value of SS_LMOUT.

This statement can be used in all ACCELL/4GL event sections except FUNCTION.

Syntax

Description

AffectedSections



This UPDATE CURRENT RECORD statement updates the database record if thedescription field has changed.

FIELD descriptionBEFORE FIELDIF (is_current_record_stored$() = FALSE THENBEGIN

UPDATE CURRENT RECORDDISPLAY ’This record has been added.’ FOR FYI_MESSAGE WAIT

END

CLEAR TO ADD, DELETE, DELETE CURRENT RECORD, DELETE SELECTEDROW, INSERT, ON FIND, UPDATE, UPDATE SELECTED ROW

Example

See Also


�

UPDATE SELECTED ROW

ACCELL/4GL update statement RDBMS dependent

�� -

�� 3

��

+��

42��.��5

��

��

INFORMIX Supported.

INGRES Supported.

ORACLE Supported.

SYBASE SQLServer

The UPDATE SELECTED ROW statement is notsupported for SYBASE SQL Server.


EXECUTING_blockAn EXECUTING clause in an SQL SELECT statement.

column_name The name of the database column to be updated.

value_expr Specifies a value expression to be inserted into the database column.

query_expr Any SELECT statement with only one database column in theselection list.

The UPDATE SELECTED ROW statement initiates a noninteractive update operationto update a row retrieved by a SELECT statement. The UPDATE SELECTED ROWstatement does not cause execution of the BEFORE UPDATE and AFTER UPDATEsections.

This statement can be used only from within an EXECUTING block. If theEXECUTING block is nested within other EXECUTING blocks, the updated row isthe row associated with the innermost block.

Syntax

Support

Arguments

Description


UPDATE SELECTED ROW

This statement can be used only when the table of the associated SELECT statementis updatable. The SELECT statement can contain no more than one table in theFROM clause and cannot contain a GROUP BY, ORDER BY, or HAVING clause.

WarningUsing an UPDATE SELECTED ROW statement to update rows that are in theform’s selected set does not update the selected set records. The selected setrecords remain unaffected by the update although their associated rows in the targettable have been updated.

If UPDATE SELECTED ROW cannot lock the selected row or if any other erroroccurs, the update operation fails.

Use the ACCELL/SQL system function status$( ) to test the success of a databaseupdate. If the user does not have update privilege, the status$( ) function returns astatus code of SS_WRACS after an unsuccessful update operation.


This UPDATE SELECTED ROW statement retrieves each row in the employee tableto update each employee’s salary based on a percentage rate. The date of last salaryincrease is then changed to the current date.

SET emp_last TOSELECT emp_last_name FROM employeeEXECUTING

BEGINIF yes_no$(’Does employee’ + emp_last + ’receive a raise?’, –1)THEN

UPDATE SELECTED ROWSET sal = (1 + $raise) * sal,

last_raise = current_date$();END

AffectedSections

Example


�

UPDATE SELECTED ROW

AFTER ADD, AFTER UPDATE, DELETE CURRENT RECORD,DELETE SELECTED ROW, EXECUTING, ON FIND, SELECT,UPDATE CURRENT RECORDstatus$( )�� !"�#�&'()!��

See Also


WHEN FIELD CHANGES

Field section Master application and standard form script

�� *��

��

��

��

��

��

��


ACCELL/Manager executes the WHEN FIELD CHANGES subsection when the valueof the form field changes. The WHEN FIELD CHANGES subsection is executed onlywhen the field value change is the result of a change that is initiated on the currentform or its form script; WHEN FIELD CHANGES is not executed if the field value ischanged from another form or from a global function.

If an ON FIELD subsection exists, ACCELL/Manager delays execution of WHENFIELD CHANGES until completion of the ON FIELD section.

The WHEN FIELD CHANGES section is a subsection of the FIELD section. Youmust introduce the WHEN FIELD CHANGES section with the FIELD section. TheFIELD section identifies the particular form field to which the WHEN FIELDCHANGES section refers.

If your form script includes a FIELD section for the field for one of the other FIELDsubsections, do not repeat the FIELD section. Only one FIELD section is requiredper form field.

You can use this subsection to calculate the value for a dependent form field. Forexample, if either price or quantity change on a form, you could recalculate theextension value (the price multiplied by the quantity) in the WHEN FIELDCHANGES section of the price field and the quantity field.

Syntax

Arguments

Description


�

WHEN FIELD CHANGES

You can also use the WHEN FIELD CHANGES subsection to perform operationssuch as displaying columns from other database tables when the value of a referencefield changes.

WarningBe careful about statements in this subsection that change the form field’s value.Changing the field value can cause ACCELL/Manager to execute the WHEN FIELDCHANGES section again, creating an infinite loop at runtime.

This statement is invalid in the following event sections:

�� )��

��

��

��

��

��6��

��6��

��

��

AFTER FIELD, BEFORE FIELD, FIELD, INIT FIELD, NEXT ACTION, ON FIELD

AffectedSections

See Also


WHILE

Control repetition statement

�� .

logical_expressionAny ACCELL/SQL BOOL expression. The expression is evaluated atthe beginning of each loop iteration. The statement_body is executedas long as this expression is TRUE.

statement_bodyAny valid ACCELL/4GL statement: either a single statement or astatement block (statements surrounded by BEGIN and END).

The WHILE statement executes statement_body until logical_expression is FALSE.

To execute the WHILE statement, the ACCELL/Manager first evaluateslogical_expression. This expression determines the number of times that thestatement body is executed.

If logical_expression evaluates to TRUE, ACCELL/Manager reexecutesstatement_body. If logical_expression initially evaluates to FALSE, thestatement_body does not execute. If logical_expression contains a null value, itevaluates to FALSE.

If logical_expression contains a variable, this variable must have an initial valueassigned before the WHILE statement so the logical_expression can be evaluated thefirst time.

ACCELL/Manager continues the process of testing the logical_expression andexecuting the statement_body until logical_expression is FALSE. When thelogical_expression is FALSE, the WHILE loop ends.

Syntax

Arguments

Description


�

WHILE

Because ACCELL/Manager evaluates the logical_expression in a WHILE statementbefore each execution of the statement body, it is possible that the WHILE statementbody might not be executed at all (if logical_expression initially evaluates toFALSE).


This WHILE statement displays the numbers 1 to 99 values in the current field andthen leaves the WHILE loop.

SET index TO 1WHILE index < 100

BEGINDISPLAY indexREFRESH SCREENSET index TO index + 1

END

BREAK, CONTINUE, FOR, REPEAT“Using Script Statements” in �� !"�#�$��% ��!��

AffectedSections

Example

See Also


WRITE PIPELINE

Output statement

��

pipe_name A standard ACCELL/SQL variable identifying the file descriptor ofthe open pipeline.

expression_list A list of ACCELL/SQL expressions separated by commas. Eachexpression is evaluated and the resulting value is sent across thepipeline pipe_name.

The WRITE PIPELINE statement sends data across an open pipeline, pipe_name. Apipeline sends information from the application to other programs. When theACCELL/Manager executes the statement, it writes the elements of expression_list tothe pipeline identified by the variable pipe_name.

To send data across a pipeline, you must first create the pipeline with the CREATEPIPELINE statement. CREATE PIPELINE creates an operating system pipeline andputs the pipeline’s file descriptor in pipe_name.

ACCELL/Manager writes the information as a stream of ASCII characters. Numbervalues (NUMERIC, FLOAT, and AMOUNT) are converted to a string containing thenumber. BOOL values are converted to the strings “YES” or “NO”. DATE and TIMEvalues are converted to their string equivalents. For each line of a TEXT value, abackslash (\) is inserted as an escape character before each newline character. Binaryvalues are truncated at the first newline or other control character or at the firstunprintable character.

ACCELL/Manager automatically inserts separator characters between the expressionsin expression_list. By default, the field separator character is a vertical bar (|). Youcan change the field separator by assigning a different character to the ACCELL/SQLSEPARATOR configuration variable.

Syntax

Arguments

Description


�

WRITE PIPELINE

ACCELL/Manager also automatically inserts a newline character (\n) at the end ofexpression_list.

You must build the items in expression_list so that the information is in the correctformat for the external programs in the pipeline. WRITE PIPELINE inserts only fieldseparators between fields and a newline at the end of the data record. To format datafor formatting programs, you can include the newline, carriage return, backspace ortab characters in the pipeline data.

Writing data in the correct format for formatting programs often involves using manyWRITE PIPELINE statements. For sending nonprinting characters with the WRITEPIPELINE statement, you can use the following escape sequences:

\b Backspace

\n Newline

\r Return (ASCII 13)

\t Tab

You can send nonprinting characters that are not listed by using the ACCELL/SQLsystem function char_code_to_str$( ).

The ACCELL/SQL Report Writer, RPT, expects input in the form of records. Eachrecord is made up of fields of data. By default, RPT expects the standard fieldseparator (|) between fields. Each record must be terminated by a newline character(\n).



WRITE PIPELINE

This WRITE PIPELINE statement sends a numeric constant (50), a string constant(’Standard Terms’), and a form variable (form:variable) to the pipeline identified by$pipe_one.

WRITE PIPELINE $pipe_one50, ’Standard Terms’, form:variable

The information is sent over pipe_one in the standard RPT format with fieldsseparated by vertical bars and a newline marking the end of the record. Ifform:variable contained the string “Region 4”, this would be the output to thepipeline:

50|Standard Terms|Region 4\n

\n is the newline character.

This WRITE PIPELINE statement sends the stock number, description and unit pricefrom all selected rows in the stock table to the pipeline identified by $pipe_two.

SET stock_num, stock_desc, stock_uprice TOSELECT st_number, st_description, st_unit_priceFROM stockWHERE st_number > 0 AND st_number < 5000EXECUTING

BEGINWRITE PIPELINE $pipe_two

stock_num, stock_desc, stock_upriceEND

CLOSE PIPELINE, CREATE PIPELINE

Example

See Also


�

XLOCK


��

INFORMIX Supported with the restrictions described below.

INGRES Supported as described.

ORACLE Supported with the restrictions described below.

SYBASE SQLServer

Supported with the restrictions described below.

Unify DataServerSupported as described.


table_name The name of the database table to be exclusive-locked or of the tablecontaining the rows to be exclusive-locked.

logical_expressionAn RDBMS Boolean expression. The expression is evaluated todetermine which database rows are issued an exclusive lock request.

An XLOCK statement issues an exclusive lock request on a database object. Thisobject can be either a table or a set of database rows. An exclusive lock grants atransaction both read and write access. When a table or row has an exclusive lock,the transaction can read and modify the object. Unless the application or RDBMSallow reading of dirty data, other transactions can neither read nor write anexclusive-locked object.


Syntax

Support

Arguments

Description


XLOCK

Using the WHERE Clause

The set of rows for which to issue the lock request is determined by the WHEREclause. XLOCK requests an exclusive lock for all rows that satisfy thelogical_expression in the WHERE clause. This logical_expression must include atest on at least one column name from the table table_name.

If the logical_expression evaluates to TRUE for a row, an exclusive lock is requested.If the logical_expression evaluates to FALSE or to a null value for a row, no lock isobtained.

If the WHERE clause is omitted, an exclusive lock is requested for the entire table.

If the RDBMS does not provide a method for exclusive-locking rows, the XLOCKstatement obtains a shared lock.

��

For INFORMIX, the WHERE clause cannot include a column having the TEXT orBYTE data type. With the WHERE clause, the XLOCK statement obtains sharedlocks on the selected rows. Without the WHERE clause, the XLOCK statementobtains a shared lock on the table.

��

For ORACLE, the WHERE clause cannot include a column having the LONG orLONG RAW data type. With the WHERE clause, the XLOCK statement obtains shareupdate row locks on the selected rows. Without the WHERE clause, the XLOCKstatement obtains an exclusive lock on the table.

�� !�

For SYBASE SQL Server, the XLOCK statement with the WHERE clause obtainsshared locks on the selected rows. Without the WHERE clause, the XLOCKstatement obtains a shared lock on the table.


�

XLOCK

Controlling Locks

Execution of an XLOCK statement does not guarantee that the row or table isexclusive-locked. The statement generates a request for an exclusive lock on theobject. If the request cannot be granted, another transaction is probably holding aconflicting lock.

You can use the status$( ) system function to test the success of an XLOCKstatement. Any time an XLOCK requests an exclusive lock on a set of rows, the lockrequest fails if any one of the rows cannot be exclusive-locked. In this case, thestatus$( ) system function returns an SS_LMOUT status code.

You can write your application so that it attempts a lock several times if an XLOCKfails. If, after repeated attempts, the XLOCK request still fails, it is best to restart thetransaction and release all locks.

The Start Tx transaction level releases all locks held by the current transaction beforeit starts a new transaction. Using Start Tx is the only way to directly release anexclusive lock. You can use the CHOOSE FIRST FORM and CHOOSE NEXTFORM statements to specify a transaction level.


This XLOCK statement requests an exclusive lock on the entire stock table.

XLOCK stock ;

This XLOCK statement requests an exclusive lock on all rows in the stock table witha stock number greater than 5000.

XLOCK stockWHERE st_number > 5000 ;

CHOOSE FIRST FORM, CHOOSE NEXT FORM, COMMIT WORK, EXECUTING,INSERT, SELECT, SLOCK, UNLOCKstatus$( )�� !"�#�&'()!��

AffectedSections

Example

See Also


ZOOM RETURN VALUES


)�� +��3��+��4� �� +��

variable The name of the variable for the value that is to be returned from thezoom form.

The ZOOM RETURN VALUES statement specifies the names of the variables fromwhich the values are to be obtained when the user returns values from a zoom form.This statement can be used in a zoom form script to specify return fields or variableswhen the RDBMS does not provide primary keys in the database.

If the script for the form that invokes the zoom form has no ENABLE ZOOMstatement, the ZOOM RETURN VALUES statement has no effect. If the ENABLEZOOM statement includes the INTO clause, the number of values in the INTO clausemust correspond to the number of values in the ZOOM RETURN VALUES statement.

This statement can be used in any ACCELL/4GL event section.

In this example, the Salesrep and Exp fields on the Company form are assigned thevalues contained in the Name and Ext fields on the Salesreps form.

In the Company form script:

ENABLE ZOOM RECORD_CONSISTENCY TO SalresrepsRETURN VALUES INTO Salesrep, Ext

In the Salesreps form script:

BEFORE FORMZOOM RETURN VALUES Name, Ext

DISABLE ZOOM, ENABLE ZOOM

Syntax

Arguments

Description

AffectedSections

Example

See Also


�

331

System Functionsand Variables

��

��

332 System Functions and Variables

��

This chapter provides complete descriptions of all ACCELL/4GL systemvariables and system functions. The descriptions appear in alphabeticalorder. Each description includes several parts:

Indicates the beginning of a syntax description.


Category The category, or type, of function or variable is shownbeneath the section name. Dependencies, if any, are alsoindicated.

Syntax Presents the syntax for the system function or variable.BOLDFACE words are keywords. Shaded areas indicatefeatures that are restricted to a particular user interface,operating system, or RDBMS. Italicized words within thesyntax are described under Arguments.


Arguments Describes the italicized arguments shown in the syntax.Only system functions have arguments.

Return Values Describes the values returned by the system function.

Legal Values Describes the values that the variable can assume.

Description Describes usage and any special conditions and notes.

Example Gives a sample that shows how the function or variablemight be used.

See Also Lists other functions, variables, or manuals that arerelated to the function or variable.

333System Functions and Variables

add_allowed$

System variable Database operations

��

(BOOL)

TRUE The user has permission to perform interactive add operations on anyform.

FALSE The user does not have permission to perform interactive addoperations on any form.

The add_allowed$ system variable controls the user’s application access privilegefor interactive add operations. The application access privileges control whatinteractive database operations the user has access to on all standard applicationforms. These privileges are application-wide: they apply to interactive operations onall standard forms.

The application access privilege is initialized by the access code argument whenACCELL/Manager begins execution of the application. This access code is an integerin the range 0 to 15 that determines which of the four interactive operations areallowed in the application.

If both the add_allowed$ application access privilege and the ADD_ALLOWEDform access privilege are set to TRUE, the user is allowed to perform interactive addoperations. If either the add_allowed$ application access privilege or theADD_ALLOWED form access privilege is set to FALSE, the user cannot performinteractive add operations. The ADD_ALLOWED form access privilege is a formattribute and can be set from the ACCELL/Generator Form Definition form or fromwithin the form script.

Syntax

LegalValues

Description


add_allowed$

In this example, the group_id$( ) system function determines the user’s group ID. Itthen sets the add operation permission to TRUE if the user belongs to a group withan ID of 10.

IF (group_id$() = 10) THENSET add_allowed$ to TRUE

delete_allowed$, find_allowed$, group_id$, update_allowed$ADD_ALLOWED in the “Attributes Summary” chapter of this manual��

Example

See Also


aud_mode$( )

System function Status checking

��

(BOOL)

TRUE The current form mode is add/update/delete mode.

FALSE The current form mode is find mode.

The aud_mode$( ) system function determines whether the current form mode isadd/update/delete mode. Use this function in an ON NEXT FORM or ON PREVIOUSFORM section to determine the current mode of operation from which the userpressed �� or �� .

This function is also useful in the DEFINE COMMAND section when a function keyhas an action defined in both form modes. The aud_mode$( ) function can be usedto separate the definition for the add/update/delete mode action from the definitionfor the find mode action.

In this example, the search range for the account numbers is set to 100 only if thecurrent form mode is find mode. If ACCELL/Manager located records and was inadd/update/delete mode, the application moves to the next form.

ON NEXT FORMIF ( aud_mode$() = FALSE ) THEN

BEGINSET acct:$acctno:SEARCH_RANGE TO ’100’NEXT ACTION IS FIND

END

current_record_count$( ), current_record_num$( ),is_current_record_stored$( ), record_is_current$( )

Syntax

ReturnValues

Description

Example

See Also


background$( )

System function: Process Control

��

shell (STRING) The full directory path and file name of the shell to beused for executing the command. If shell is null or a zero-lengthstring—two apostrophes (’’), the shell is determined by followingthe normal configuration variable search hierarchy:

��

��

��

��

command_string(STRING) The string containing the operating system command tobe executed.

0 The command specified by command_string was executedsuccessfully.

UNDEFINED The command_string is not a valid operating system command.

system( ) value The operating system could not execute the command_string, so thebackground$( ) function returned the value from the operatingsystem function system$( ).

The background$( ) system function executes an operating system command so thatits progress and results are not displayed on the screen. The command can be anycommand that you can execute from the operating system prompt.

This function starts an operating system subprocess and gives the command_string asinput. The operating system executes the commands in command_string and thenreturns control to ACCELL/Manager.

Syntax

Arguments

ReturnValues

Description


background$( )

This function differs from the UNIX background command and its ampersand (&)metacharacter. !!"##$�%# must wait for the background$( ) function to becompleted before continuing; application execution will pause until the functionreturns.

If you want to use background$( ) to run a lengthy procedure, you can display amessage for the user before background$( ) begins. For example, if you usebackground$( ) to clean up the file system, display a message that requests the userto wait for a few seconds.

The following example uses the background$( ) system function to format and printa report if the user answers yes in the print_report field. The job is executed by theoperating system without altering the application display.

FIELD print_reportAFTER FIELD

IF (print_report = TRUE) THEN background$(’/bin/sh’,’nroff –ms report1 | lpr’)

system$( ), push_shell$( )

Example

See Also


beep$( )

System function Screen I/O

� ��

beep_count (NUMERIC) The number of bell characters to send to the terminal.

None

The beep$( ) system function makes the user’s terminal beep by sending ASCII bellcharacters (ASCII value 7). Use this function to notify the user of some special eventsuch as an error message, invalid action, or important task.

This function has no effect if the user has disabled the bell on the terminal.

This example sends three ASCII bell characters to the user’s terminal when the item’squantity on hand in inventory reaches zero.

IF ( finventory:$nv_q_on_hand = 0 ) THENBEGIN

beep$(3)DISPLAY ’No more items in inventory — Time to reorder!’


Syntax

Arguments

ReturnValues

Description

Example


binarylen$( )

System function Binary manipulation

��

binary_value (BINARY) A binary value.

(NUMERIC) A NUMERIC value for the length of the binary value in bytes isreturned. If the BINARY value has a null value, a null NUMERICvalue is returned.

The binarylen$( ) system function determines the length in bytes of a BINARYvalue.

This example extracts a set of integers from a list of 4-byte integers.

FOR (SET $idx TO 0; $idx < (binarylen$($intlist) / 4); SET $idx TO $idx + 1)BEGIN

SET $start TO $idx * 4;SET $end TO $start + 4;SET numeric_array[$idx] TO to_num$(subbinary$($intlist,$start,$end));

END;

subbinary$( )

Syntax

Arguments

ReturnValues

Description

Example

See Also


change_schema$( )

System function: user environment RDBMS dependent

��

INFORMIX Supported.

INGRES Supported.

ORACLE The change_schema$( ) system function is not supported for theORACLE RDBMS; the function always returns FALSE.

SYBASE SQLServer

Supported.


database_name (STRING) Specifies the name of the owning database object to bemade current. The owning database object depends on the RDBMS:

INFORMIX: Specify the name of the owner to be made current.

INGRES: Specify the name of the database to be made current.

SYBASE SQL Server: Specify the name of the database to be made current.

Unify DataServer: Specify the name of the schema to be made current.

(BOOL)

TRUE The function successfully changed the current database to thedatabase specified by database_name.

FALSE The function was unable to change the current database to thedatabase specified by database_name.

Syntax

Support

Arguments

ReturnValues


change_schema$( )

The change_schema$( ) system function changes the current database or schema tothe database or schema that is specified in database_name. By using this function,you can conditionally change from one database or schema to another at runtime.The user must have permission to access the specified database.

You can use change_schema$( ) when you have multiple versions of an application,each for a different database or schema.

The current database or schema changes when the change_schema$( ) function issuccessfully executed. However, if a form is already activated and has an activeselected set, it does not yet reflect the change.

To ensure that the selected set records that are visible on the active form accuratelyreflect the current database or schema, always deactivate forms and target tablesbefore executing change_schema$( ). Therefore, the best time to change the currentdatabase or schema is when the master application form is executed, beforeactivating any forms that have target tables.

!"�#$%!&

INFORMIX does not allow changing the database with an open transaction.Therefore, change_schema$( ) commits the current transaction and starts a new onein the new schema.

!"'$()

For INGRES, when the change_schema$( ) function is used, the current databasesessions are disconnected before connecting to the new database.

The following diagram illustrates an example where duplicate inventory applicationsare maintained for two databases, Production and Testing. In both databases theform names and target table names are the same; both databases contain a Companyform and a company table. The Production database contains the data that isaccessed by application users. The Testing database contains sample data that is usedto test the application.

Description


change_schema$( )

��

Table: contact

Form: Company

Database:Production

Database:Testing

Table: contact

Table: orders

Table: items

Table: nventory

Table: employee

Table: orders

Table: items

Table: nventory

Table: employee

Table:company

��

Table:company

��

��

Master application form script:

change_schema$(Production) change_schema$(Testing)

��

� !"�#$�

�%%&��

��'��&�"�# (�

#�!��

&�"�") #��

!�*#�") #��

�*�$�

� #��

") #��

�*�'��


change_schema$( )

The following example displays a message if the function cannot change the currentdatabase:

IF NOT change_schema$(CompTut) THENDISPLAY ’Unable to change database.’ FOR FYI_MESSAGE WAIT

�� ACCELL/SQL: RDBMS Integration

Example

See Also


char_code_to_str$( )

System function String conversion

��

ascii_value (NUMERIC) The decimal ASCII value to be translated into acharacter.

(STRING) The single character representation of the ASCII value ascii_value.

The char_code_to_str$( ) system function translates an integer ascii_value into asingle character string. The ascii_value must be an integer in the range 0 to 255(valid ASCII values).

This function is used primarily to include nonprinting characters in strings.

This SET statement uses char_code_to_str$( ) to assign the ASCII representation of^c (CTRL c) to the variable ctrlC.

SET ctrlC TO char_code_to_str$(3)

str_to_char_code$( )

Syntax

Arguments

ReturnValues

Description

Example

See Also


check_dirty$( )

System function: status checking RDBMS dependent

� ��

INFORMIX The check_dirty$( ) function always returns TRUE because dirtydata cannot be detected and is always read if no lock is requested.

INGRES The check_dirty$( ) function always returns TRUE because dirtydata cannot be detected and is always read if no lock is requested.

ORACLE The check_dirty$( ) function always returns TRUE.

SYBASE SQLServer

The check_dirty$( ) function always returns FALSE becauseSYBASE SQL Server does not allow users to read dirty data.

Unify DataServerFully supported. The check_dirty$( ) returns TRUE if the selectedset or the current record contains locked records and FALSE if theselected set contains no dirty data.

(BOOL)

TRUE Where check_dirty$( ) is fully supported, TRUE indicates that theselected set or the current record contains dirty data.

FALSE The selected data does not contain dirty data.

If fully supported by the underlying RDBMS, the check_dirty$( ) system functiondetermines whether the results of a database access encountered dirty data. Dirty datais data in a database row that was exclusive-locked by another transaction when thecurrent transaction tried to access it.

If a row is exclusive-locked, it is usually because some other transaction is updating,deleting, or adding the row. The data in this exclusive-locked row might be beingupdated or deleted by another transaction. The exclusive-locked row might not havethe same column values in the database when the exclusive lock is released. If therow has been deleted, the values might not even exist.

Syntax

Support

ReturnValues

Description


check_dirty$( )

If the RDBMS supports the show_dirty_data option, you can use the ACCELL/SQLsystem function show_dirty$( ) to specify whether dirty data is brought into theapplication.

If the application allows dirty data, column values for exclusive-locked rows arebrought into the application.

If the application does not allow dirty data, column values for exclusive-locked rowsare not brought into the application.

DependenciesUnify DataServer. You can use check_dirty$( ) to determine whether dirty data wasaccessed:

If the application allows dirty data and if the database accessedexclusive-locked rows, check_dirty$( ) returns TRUE. If no dirty data wasencountered, check_dirty$( ) returns FALSE.

If the application does not allow dirty data, column values forexclusive-locked rows are not brought into the application. You can usecheck_dirty$( ) to determine whether any exclusive-locked rows wereaccessed, even though their column values are not available.

&��''�� (� �� )�*"+(�!"(+��*��+��,� ��(��(�'��(��-

an interactive find operation: if the current transaction is running at recordconsistency

a noninteractive find: if the SELECT statement does not include a lockingclause

.�� (�� '�� (�� (��*��+��,� �

/�� '��)�� #"��!"+

��,�� (�� &�� (�� )��$(,(-�$(#$+��.�� .�-($��!"+��,��(��

/�� '��)�� (&(*-!"'��)(/(-��,�� (�� )(/(-��,�(�� (��


check_dirty$( )

In this example, check_dirty$( ) checks the results of a database search on a targettable. If the selected set contains dirty data, the code sample asks if the user wants tocontinue using the selected set. If the end user answers NO, this code sample clearsthe selected set.

AFTER FINDIF check_dirty$() THEN

BEGINDISPLAY ’Selected set contains dirty data.’

FOR FYI_MESSAGE WAITIF ( NOT yesno$(

’Do you want to co>22>2>ntinue with this selected set?’, 0) )THEN

NEXT ACTION IS CLEAR TO FINDEND

show_dirty$( )��!"#��$ ��

Example

See Also


clip_str$( )

System function String manipulation

��

value (STRING/TEXT) The string or text from which to remove leadingand trailing blanks.

(STRING) The clipped string or text (with leading and trailing blanks removed).

The clip_str$( ) system function removes leading and trailing blanks from a string ortext value. For text values, leading and trailing newline characters are also removed.If value is a null or a zero-length value, clip_str$( ) returns value. This function doesnot remove embedded blanks. This function is useful for removing extra blanks froma database string column.

This example extracts a menu item from mnu_table and stores the clipped menuitem in mnu_item.

SET mnu_item TO SELECT mnu_item_name FROM mnu_table WHERE mnu_id = $id;SET mnu_item TO clip_str$(mnu_item)

strlen$( ), substr$( )

Syntax

Arguments

ReturnValues

Description

Example

See Also


close_message_file$( )

System function Message files

��

None

The close_message_file$( ) system function closes a previously opened message file.Only one message file can be open at a time.

Messages are stored in a message file, one per line, in a special format. For acomplete description of the message file format, see the description for theACCELL/SQL system function get_message$( ).

In this example, open_message_file$( ) opens the message file /usr/apps/messages.If this message file can be opened, the code sample retrieves a message from it usingget_message$( ). After the message is retrieved, the message file is closed byclose_message_file$( ).

IF ( open_message_file$(’/usr/apps/messages’) = 0 ) THENBEGIN

DISPLAY get_message$(100) FOR FYI_MESSAGE WAITclose_message_file$()

END

get_message$( ), open_message_file$( )

Syntax

ReturnValues

Description

Example

See Also


current_date$( )

System function User environment

��

(DATE ) The DATE value of the current date as retrieved from the operatingsystem.

The current_date$( ) system function obtains the current date from the operatingsystem. This date is in the same format as the ACCELL/SQL data type DATE.

In this example, current_date$( ) assigns the current date to the ld_date_foundvariable if this variable was undefined.

FIELD ld_date_foundAFTER FIELD

IF ( fleads:ld_date_found IS UNDEFINED ) THENSET fleads:ld_date_found TO current_date$()

current_time$( ), date_to_mdy$( )

Syntax

ReturnValues

Description

Example

See Also


current_record_count$( )


��

(NUMERIC)

> 0 The number of records in the selected set.

0 The form is in find mode, or no records have been selected.

The current_record_count$( ) system function determines the number of records inthe selected set. While the form is in find mode, this function always returns zero (0).After completing a successful find, the function returns the number of recordsselected from the database. This record count is adjusted if records are added to ordeleted from the selected set.

In this example, current_record_count$( ) determines whether a database search hassuccessfully located matching records. If no records have been found, the user isasked to reenter the search criteria.

AFTER FINDIF ( current_record_count$() = 0 ) THEN

BEGINDISPLAY

’Search found�no�records, please�reenter�search criteria’FOR FYI_MESSAGE WAIT

NEXT ACTION IS CLEAR TO FINDEND

CHANGE CURRENT RECORDaud_mode$( ), current_record_num$( ), is_current_record_stored$( ),record_is_current$( )

Syntax

ReturnValues

Description

Example

See Also


current_record_num$( )


��

(NUMERIC)

> 0 The relative number of the current record within the selected set.

0 The form is in find mode, or no records have been selected.

The current_record_num$( ) system function determines the relative number of thecurrent record within the selected set. For example, if the selected set contains fiverecords and the third record in this set is displayed on the form,current_record_num$( ) returns the value 3.

When the �� command is executed, the current record number is onegreater than the current record count.

In this example, current_record_num$( ) and current_record_count$( ) determinewhether the current record is the last record of the selected set. If the current record isthe last record, this code puts the form in add/update/delete mode.

ON NEXT RECORDIF ( current_record_num$() = (current_record_count$() ) THEN

NEXT ACTION IS CLEAR_TO_ADD

aud_mode$( ), current_record_count$( ), is_current_record_stored$( ),record_is_current$( )

Syntax

ReturnValues

Description

Example

See Also


current_time$( )


��

(TIME) The TIME value of the current time as retrieved from the operatingsystem.

The current_time$() system function obtains the current time from the operatingsystem. This time is in the same format as the ACCELL/SQL data type TIME.

In this example,current_time$() assigns the current time to the time_enteredvariable if time_entered is undefined.

FIELD time_enteredAFTER FIELD

IF ( time_entered IS UNDEFINED ) THENSET time_entered TO current_time$()

current_date$( )

Syntax

ReturnValues

Description

Example

See Also


date_to_mdy$( )

System function Date conversion

�� %�� %��%��

date (DATE) The DATE value to be converted.

month (NUMERIC) A variable to receive the month of the converted date.This parameter is an ACCELL/SQL result parameter.

day (NUMERIC) A variable to receive the day of the converted date.This parameter is an ACCELL/SQL result parameter.

year (NUMERIC) A variable to receive the year of the converted date.This parameter is an ACCELL/SQL result parameter.

The return values for this function are returned through the arguments month, day,and year. The actual return value for this function is undefined.

The date_to_mdy$( ) system function converts date to three NUMERIC values:month, day, year. These three values correspond to the month, day, and year of theDATE value in date. The year is returned as a four-digit number.

In this example, date_to_mdy$( ), mdy_to_date$( ), and current_date$( ) are usedto create a DATE variable with a date of five years from the current date.

SET today_date TO current_date$()date_to_mdy$(today_date, month, day, year)SET year TO year + 5SET five_years TO mdy_to_date$(month, day, year)

current_date$( ), mdy_to_date$( ), str_to_date$( ), to_date$( )

Syntax

Arguments

ReturnValues

Description

Example

See Also


db_type$( )


��

(STRING) The keyword that specifies the current RDBMS type:

INFORMIX: INFORMIX

INGRES: UNGRES

ORACLE: ORACLE

SYBASE SQL Server: SYBASE

Unify DataServer:U2000

The db_type$( ) system function enables you to write statements specific to aparticular RDBMS. db_type$( ) takes no arguments and returns the name of thecurrent RDBMS type as a string.

This example causes an error message to appear if the user enters the [ metacharacterwhile using the ORACLE RDBMS.

IF db_type$() = ’ORACLE’ THENDISPLAY ’”[” metacharacter not supported’ FOR FYI_MESSAGE WAIT

os_type$( ), ui_type$( )DBTYPE in �� &�� '�� (��!�&��

Syntax

ReturnValues

Description

Example

See Also


dbms_status$( )


��

(NUMERIC) A return code supplied by the database.

The dbms_status$( ) system function returns a specific status code from the RDBMS.The values returned are specific to each RDBMS.

ORACLE Version 7 can return multiple error messages for a single executablestatement. The error messages are returned as one long string that contains embeddederror numbers.

dbms_status$( ) returns the first error code found in the string of multiplemessages.

sql_errmsg$( ) returns the entire string of multiple messages.

To obtain information about the messages that were returned for a statement, usethese new ACCELL/SQL system functions: sql_errmsg_count$( ), sql_errmsg_i$( ),or dbms_status_i$( ).

In this example, dbms_status$( ) determines whether any records were found in anoninteractive find operation. If no records were found, the emp_name variable isset to a string of spaces.

SET emp_name TO SELECT name FROM employee WHERE emp_num = $emp_id;IF NOT_FOUND_STAT = dbms_status$()THEN

SET emp_name TO ” ”;

dump_statistics$( ), sql_errmsg$( ), sql_state$( ), sql_code$( ), status$( )��!"#��$ �� Database error code documentation supplied by the RDBMS vendor

Syntax

ReturnValues

Description

Example

See Also


dbms_status_i$( )

System function: error message handling RDBMS dependent

�� )�

INFORMIX The dbms_status_i$( ) function always returns NULL because thefunction is not supported for this RDBMS.

INGRES The dbms_status_i$( ) function always returns NULL because thefunction is not supported for this RDBMS.

ORACLE The dbms_status_i$( ) function works exactly as described.

SYBASE SQLServer

The dbms_status_i$( ) function always returns NULL because thefunction is not supported for this RDBMS.

Unify DataServerThe dbms_status_i$( ) function always returns NULL because thefunction is not supported for this RDBMS.

index Index, ranging from 1 to n, that indicates the message in the errormessage string that was generated by the last call to the database.

error_code (NUMERIC) The ORACLE-specific error code that corresponds tothe index-indicated error message in the error message string thatwas generated by the last call to the database.

NULL The index value is out of range, or the underlying RDBMS is notORACLE Version 7.

The dbms_status_i$( ) system function returns the ORACLE DBMS error code thatcorresponds to the index-indicated error message in the error message string that wasgenerated by the last database operation that generated a call to the server. Thedatabase operation can be initiated by either ACCELL/Manager or adeveloper-defined C function.

Syntax

Support

Arguments

ReturnValues

Description


dbms_status_i$( )

FOR (SET inx TO 1; inx < sql_errmsg_count$(); SET inx TO inx + 1) BEGIN DISPLAY dbms_status_i$(inx) FOR FYI_MESSAGE WAIT END

sql_errmsg_count$( ), sql_errmsg_i$( )

Example

See Also


delete_allowed$


� � � ��

(BOOL)

TRUE The user has permission to perform interactive delete operations onany standard form.

FALSE The user does not have permission to perform interactive deleteoperations on any standard form.

The delete_allowed$ system variable controls the user’s application access privilegefor interactive delete operations. The application access privileges control whatinteractive database operations the user has access to on all application forms. Theseprivileges are application-wide: they apply to interactive operations on all forms.


If both the delete_allowed$ application access privilege and theDELETE_ALLOWED form access privilege are set to TRUE, the user is allowed toperform interactive delete operations. If either the delete_allowed$ applicationaccess privilege or the DELETE_ALLOWED form access privilege is set to FALSE,the user cannot perform interactive delete operations. The DELETE_ALLOWEDform access privilege is a form attribute and can be set from the ACCELL/GeneratorForm Definition form or from within the form script.

Syntax

LegalValues

Description


delete_allowed$( )

In this example, the group_id$( ) system function is used to determine the user’sgroup ID. It then sets the delete operation permission to TRUE if the user belongs toa group with a group ID of 10.

IF (group_id$() = 10) THENSET delete_allowed$ to TRUE

add_allowed$, find_allowed$, group_id$( ), update_allowed$DELETE_ALLOWED in the “Attributes Summary” chapter of this manual��

Example

See Also


dump_statistics$( )


��

None

The dump_statistics$( ) function prints statistics about ACCELL/Manager internalmemory use. Statistics are printed to the file specified by the AMGR_ERFLconfiguration variable. The statistics include heap memory, stack memory, form andfunction caches, and memory used for arrays. You can use these statistics todetermine the appropriate amount of memory to specify for associated configurationvariables.

The statistics generated by dump_statistics$( ) are the same as those generated bypressing �� from ACCELL/Manager during application execution.

This example prints statistics before exiting the application if the $debug variableindicates that the application is in debug mode.

ON EXITIF ($debug = TRUE) THEN

dump_statistics$()

dbms_status$( )�� &�� '�� (��!�&��

Syntax

ReturnValues

Description

Example

See Also


explicit_mode$( )


0�� )��&��

explicit_mode_flg(BOOL) A flag that specifies whether to enable the explicit searchmode (flag is TRUE) or the default search mode (flag is FALSE).

(BOOL)

TRUE The search mode indicated by explicit_mode_flg was successfullyenabled.

FALSE The search mode indicated by explicit_mode_flg was notsuccessfully enabled. Explicit_mode_flg is not a valid BOOL valueor is undefined.

The explicit_mode$( ) system function sets the search mode that ACCELL/Manageruses when it searches for STRING values. The initial search mode is determined bythe setting of the EXPL_MODE configuration variable. You can use theexplicit_mode$( ) system function to change the initial setting on a form-by-formbasis.

If explicit_mode_flg is TRUE, explicit search mode is used for string searches. Inexplicit search mode, ACCELL/Manager searches for strings that match the searchcriteria exactly. If explicit_mode_flg is FALSE, ACCELL/Manager uses the defaultsearch mode for string searches. In default search mode, ACCELL/Manager searchesfor all strings that begin with the string specified in the search criteria. However, ifthe string is associated with a STRING database column that is a primary key,explicit search mode is used.

Syntax

Arguments

ReturnValues

Description


explicit_mode$( )

You can achieve field-by-field control of the search mode by settingexplicit_mode$( ) to TRUE in the ON CLEAR TO FIND section; then append anasterisk to the SEARCH_RANGES value of specific fields in the BEFORE FINDsection, for example:

SET co_name TO co_name:SEARCH_RANGES + ’*’

This example tells ACCELL/Manager to use the default search mode for all searcheson this form.

BEFORE FORMIF ( explicit_mode$(FALSE) ) THEN

DISPLAY ’Searches on this form are performed in default search mode’FOR FYI_MESSAGE WAIT

ELSEDISPLAY ’Internal error: unable to set search mode’

FOR FYI_MESSAGE WAIT

SEARCH_RANGES target variable attributeEXPL_MODE in �� &�� '�� (��!�&�� “Find Mode” in ��*�� +��

Example

See Also


find_allowed$


��

(BOOL)

TRUE The user has permission to perform interactive find operations onany standard form.

FALSE The user does not have permission to perform interactive findoperations on any standard form.

The find_allowed$ system variable controls the user’s application access privilegefor interactive find operations. The application access privileges control whatinteractive database operations the user has access to on all standard applicationforms. These privileges are application-wide: they apply to interactive operations onall forms.


If both the find_allowed$ application access privilege and the FIND_ALLOWEDform access privilege are set to TRUE, the user is allowed to perform interactive findoperations. If either the find_allowed$ application access privilege or theFIND_ALLOWED form access privilege is set to FALSE, the user cannot performinteractive find operations. The FIND_ALLOWED form access privilege is a formattribute and can be set from the ACCELL/Generator Form Definition form or fromwithin the form script.

Syntax

LegalValues

Description


find_allowed$

In this example, the group_id$() system function is used to determine the user’sgroup ID. The find operation permission is then set to TRUE if the user belongs to agroup with a group ID of 10.

IF (group_id$() = 10) THENSET find_allowed$ to TRUE

add_allowed$, delete_allowed$, group_id$( ), update_allowed$FIND_ALLOWED in the “Attributes Summary” chapter of this manual��

Example

See Also


flush_to_disk$( )

System function: Process control

��

None

The flush_to_disk$( ) system function tells ACCELL/Manager to call the UNIXoperating system function, sync( ). The sync( ) function causes the operating systemto write the current user memory buffers to disk.

Calling flush_to_disk$( ) flushes all previously unwritten buffers out to disk so thatall file modifications up to this point are saved.

Additional HelpFor more information about sync( ), refer to your operating system referencemanuals.

In this example, flush_to_disk$( ) ensures that all information for the currenttransaction has been saved to disk before the transaction on the next form begins.

ON NEXT FORMflush_to_disk$()

Syntax

ReturnValues

Description

Example


fyi_refresh_mode$( )

System function: Process control Character user interface

� �� )��

bool_expr (BOOL) A Boolean expression that is evaluated as TRUE or FALSE.

If bool_expr evaluates to TRUE (default), refresh mode is used.If bool_expr evaluates to FALSE, no-refresh mode is used. If bool_expr evaluates to NULL or UNDEFINED, the previous modeis returned, but the mode is not changed.

(BOOL)

TRUE The previous mode was refresh mode.

FALSE The previous mode was no-refresh mode.

UNDEFINED An invalid bool_expr was specified.

The fyi_refresh_mode$( ) system function controls when field FYI messages aredisplayed. If refresh mode is on, a field’s FYI message text overwrites other messagesthat are displayed in the fyi_message system information field.

The fyi_refresh_mode$( ) system function enables FYI messages that are displayedby the DISPLAY statement to remain displayed and not be overwritten by the field’sFYI message. When the WAIT clause is not included in the DISPLAY statement, thefield’s FYI message immediately overwrites the displayed message.

DependenciesGraphical user interfaces display most messages in notice boxes or dialog boxes thatare not affected by refresh mode. Therefore, for GUIs, only FYI messages that aredisplayed without the WAIT clause are affected by the refresh mode.

The following table summarizes the effects of refresh mode versus no-refresh mode.

Syntax

Arguments

ReturnValues

Description



The Effects of Refresh Mode Versus No-Refresh Mode

Event Refresh Mode No-Refresh Mode

Cursor is moved to thefield

Field’s FYI message isdisplayed

Field’s FYI message isdisplayed

Cursor is moved to anotherfield

The fyi_message systeminformation field is clearedand the new field’s FYImessage is displayed

The fyi_message systeminformation field is clearedand the new field’s FYImessage is displayed

DISPLAY expression FORFYI_MESSAGE is executed

The displayed message isoverwritten whenACCELL/Manager returns tothe field. (This can cause themessage to be unreadable.)

The displayed messageremains displayed untilanother event causes themessage to be changed

DISPLAY expression FORFYI_MESSAGE WAIT isexecuted

The displayed message isoverwritten by the field’sFYI message as soon as thefirst message isacknowledged.

The displayed messageremains until another eventcauses the message to bechanged. The message mustbe acknowledged beforeinput can continue.

Error or DIS (Unify DataServerData Integrity Subsystem)message is displayed

The message must beacknowledged and isoverwritten after it isacknowledged.

The message does not needto be acknowledged, and abeep is sounded to alert theuser. The message remainsdisplayed until another eventcauses the message to bechanged.

Error or DIS screen isdisplayed

The screen must beacknowledged and isoverwritten after it isacknowledged.

The screen must beacknowledged and isoverwritten after it isacknowledged.

RESTART ON FIELD isexecuted

The field’s FYI message isredisplayed.

The field’s FYI message isnot redisplayed if aDISPLAY . . . FORFYI_MESSAGE wasexecuted in the same ONFIELD section.



In this example, fyi_refresh_mode$( ) is used to change to no-refresh mode. Amessage is displayed when a value of zero (0) is typed in the fielda field, but themessage does not need to be acknowledged and remains displayed until the user exitsthe field.

FIELD fielda BEFORE FIELD SET fyi_mode TO fyi_refresh_mode$(FALSE)

ON FIELD INPUT IF ($fielda = 0) BEGIN DISPLAY ’Enter a value other than zero (0)’ FOR FYI_MESSAGE RESTART ON FIELD END

DISPLAY, RESTART ON FIELD

Example

See Also


get_default_schema$( )


� ��

(STRING) INFORMIX: Returns the name of the default owner.

INGRES: Returns the name of the current database.

ORACLE: Returns the name of the default user.

SYBASE SQL Server: Returns the name of the default database.

Unify DataServer: Returns the name of the default schema.

The get_default_schema$( ) function returns the name of the database, owner,schema, or user under which ACCELL/Manager was started.

On systems where users are required to log into the database, you can use theget_default_schema$( ) function with the get_password$( ) function to pass thecurrent database user name and password to programs that need database logininformation. For example, the Menu Handler uses get_default_schema$( ) andget_password$( ) to pass the user name and password to executables.

In this example $command contains the name of a command to be executed. Theget_default_schema$( ) and get_password$( ) functions are used to append theuser’s default schema name and password to the command string; then the system$( )function is called to execute the command string.

SET $schema_name TO get_default_schema$()SET $password TO get_password$()SET $command TO $command + ’ –U ’ + $schema_name + ’ –P ’ + $passwordsystem$ ($command)

get_password$( ), user_id$( ), group_id$( ), group_name$( ), user_name$( )

Syntax

ReturnValues

Description

Example

See Also


get_line_of_text$( )

System function Text manipulation

� �� 0�� )�� %��

(TEXT)

text_value A value of type TEXT.

line_number The number of a line within text_value. The value of the first line oftext is 1.

(TEXT) A TEXT value is returned. If the value is NULL or if line_numberexceeds the length of the text, the value returned is UNDEFINED.

The get_line_of_text$( ) system function retrieves the specified line of text fromtext_value.

The following example creates a numbered report from a TEXT value named$text_val.

SET $inx TO 1SET $text_line TO get_line_of_text$($text_val, $inx)WHILE $text_line IS NOT UNDEFINED BEGIN SET $tmp_text TO ’Line #’ + to_string$(inx) + ’:’ + $text_line WRITE PIPELINE $text_rpt $tmp_text SET $inx TO inx + 1 SET $text_line TO get_line_of_text$($memo, $inx) END

Syntax

Arguments

ReturnValues

Description

Example


get_message$( )


� ��

message_number(NUMERIC) The integer message number of the message to beretrieved from the message file.

(STRING)

string The message string corresponding to message_number.

UNDEFINED The specified message_number is not numeric or is undefined.

NULL The specified message_number is null.

The get_message$( ) system function retrieves a message from the current messagefile. The get_message$( ) function looks for a line in the message file that beginswith the number message_number. If message_number is a null value,get_message$( ) produces a runtime error.

The message file assigns an integer message number to each message string. Lines inthe message file have the format:

#### | xxxxxxxxxxxxxxxxxx

where #### is the line’s message number, | is the delimiter, andxxxxxxxxxxxxxxxxxx is the message text. The message line numbers must be inascending order. The delimiter is any character following the first blank.

A message file must first be opened with the open_message_file$( ) function beforeget_message$( ) can retrieve messages. To close the message file, you must use theclose_message_file$( ) system function.

Using a message file instead of embedding the messages in your code significantlyreduces memory usage at runtime as well as simplifying code maintenance. Messagefiles are also very useful for internationalizing your application.

Syntax

Arguments

ReturnValues

Description


get_message$( )

A message file named /usr/apps/messages includes the following lines:

98 | Invalid entry, please try again! 99 | Inventory number out of range 100 | Record not updated! 101 | Record updated and stored!

In the following example, if the /usr/apps/messages message file can be opened,get_message$( ) retrieves message 100.



END

If get_message$( ) is successful, it displays message 100 in the fyi_message systeminformation field:

Record not updated!

close_message_file$( ), open_message_file$( )

Example

See Also


get_password$( )


� ��

INFORMIX The get_password$( ) system function always returns UNDEFINEDbecause users are not required to log in to the database.

INGRES The get_password$( ) system function always returns UNDEFINEDbecause users are not required to log in to the database.

ORACLE Supported.

SYBASE SQLServer

Supported.

Unify DataServerThe get_password$( ) system function always returns UNDEFINEDbecause users are not required to log in to the database.

(STRING)

passwd_string The current user’s database password.

UNDEFINED The password cannot be determined.

The get_password$( ) function returns the password that was used to log in to thedatabase.

You can use the get_password$( ) function with the get_default_schema$( )function to pass the current database password and user name to programs that needdatabase login information. For example, the menu handler uses get_password$( )and get_default_schema$( ) to pass the password and user name to executables.

Syntax

Support

ReturnValues

Description


get_password$( )

In this example $command contains the name of a command to be executed. Theget_default_schema$( ) and get_password$( ) functions are used to append theuser’s default schema name and password to the command string; then the system$( )function is called to execute the command string.

SET $schema_name TO get_default_schema$()SET $password TO get_password$()SET $command TO $command + ’ –U’ + $schema_name + ’ –P ’ + $passwordsystem$ ($command)

get_default_schema$( ), user_id$( ), group_id$( ), group_name$( ), user_name$( )��!"#��$ ��

Example

See Also


getenv$( )


� � �1�� &��

config_variable(STRING) A string containing the name of the environment orconfiguration variable with the value you need.

(STRING)

value The value of the config_variable (set at the operating systemcommand level or in a configuration file).

UNDEFINED config_variable is set neither in the operating system environmentnor in a configuration file.

The getenv$( ) system function obtains the value of the configuration variable listedin config_variable.

To obtain the value of config_variable, getenv$( ) looks in the following sources inthe order listed:

the operating system command-level environment

the unify.cf file in the $UNIFY directory

the system software defaults

If the config_variable is not found in any of these sources, getenv$( ) returnsUNDEFINED.

This function is useful for checking the values of configuration variables in the user’senvironment before determining what actions to take.

Syntax

Arguments

ReturnValues

Description


getenv$( )

This SET statement uses getenv$( ) to obtain the value of the configuration variableDBPATH. It then assigns this value to the variable path_name.

SET path_name TO getenv$(’DBPATH’)

�� &�� '�� (��!�&��

Example

See Also


glob_str_compare$( )

System function String or text comparison

�� %��,��

variable (STRING/TEXT) The string or text to be compared.

mask (STRING) A string containing the metacharacters and characters ofthe search pattern.

(BOOL)

TRUE variable value matches the mask.

FALSE variable value does not match the mask, or variable value is a nullstring, or mask is a null string.

The glob_str_compare$( ) system function compares a variable value with a specialstring mask. This mask describes the strings that are valid. If variable value matchesany of the strings described by the mask, glob_str_compare$( ) returns a value ofTRUE.

With glob_str_compare$( ), you use a special string specification notation to createa pattern mask. The mask string is made up of string metacharacters and characters.String metacharacters have a special meaning within the search pattern. Theydescribe certain matching patterns.

All ordinary characters (all characters except *, ?, [, ], – and \) match themselves. Todescribe a string that includes a metacharacter as an actual character, precede theoccurrence of the metacharacter with a backslash (\). The backslash overrides themetacharacter meaning of the character that follows.

Syntax

Arguments

ReturnValues

Description



If a search string includes a single left bracket ([) or right bracket (]) character, thebracket does not need to be escaped. The bracket is evaluated simply as the bracketcharacter, as show in the following examples:

�� 0��

23�� 3��3��

4.533 .3531��)��(��)�� ,��-�3

The following table defines the string specification metacharacters forglob_str_compare$( ).

��

Symbol Matches Example Results

? Any single character ABC? Any string of four characters thatstarts with ABC: ABCD, ABCE,ABC1, and so on

* Any string ofcharacters, includingzero length strings

A*C Any string that begins with A andends with C: AC, AaC, ABC,A123C, AaaaaC, and so on

[ ] Any character fromamong the list ofcharacters specifiedwithin the brackets

A[BCD]E String values: ABE, ACE, andADE

– A range of values [5–8]

[a–z]

Any of the characters 5, 6, 7, or 8

Any lowercase character



In this example, glob_str_compare$( ) compares a_strng and the mask for a stringof three digits.

IF ( glob_str_compare$(a_strng, ’[0–9][0–9][0–9]’) ) THENDISPLAY ’Matched String!’ FOR FYI_MESSAGE WAIT

When the variable a_strng contains a string of three digits, the code sample displaysthe following message in the fyi_message system information field.

Matched String!

reg_exp_str_compare$( )

Example

See Also


group_id$( )


��

(NUMERIC) The operating system group ID number of the user.

The group_id$( ) system function obtains the user’s group ID number. This group IDis obtained from the operating system password file. On most operating systems, thispassword file is /etc/passwd. This function allows you to take advantage of thesecurity groups already set up by the operating system. You can take actions in yourapplications based upon the operating system group to which the particular userbelongs.

In this example, group_id$( ) is used to determine the group ID of the user who iscurrently executing the application. If this group ID is equal to 6, the selected row isrejected and no selected set record is created.

ON FINDIF ( group_id$() = 6 ) THEN

REJECT RECORD

add_allowed$, delete_allowed$, find_allowed$, get_default_schema$( ),get_password$( ), group_name$( ), user_id$( ), user_name$( )

Syntax

ReturnValues

Description

Example

See Also


group_name$( )

System function: User environment Operating system dependent

��

(STRING) The operating system group name of the user.

The group_name$( ) system function obtains the name of the user’s group. Thisfunction enables you to take advantage of the security groups already set up by theoperating system.

You can take actions in your applications based upon the operating system group towhich the particular user belongs.

In this example, group_name$( ) is used to determine the group name of the userwho is currently executing the application. If the user belongs to the group payroll,the user is allowed to update the employee salary information.

IF ( group_name$() = ’payroll’ ) THENUPDATE employee

SET emp_salary TO femployee:new_salaryWHERE emp_name = femployee:emp_lname

get_default_schema$( ), get_password$( ), group_id$( ), user_id$( ),user_name$( )

Syntax

ReturnValues

Description

Example

See Also


info_level$

System variable User information level

�� 1 ��

0 Sets the user information level to Novice (default value).

1 Sets the user information level to Intermediate.

2 Sets the user information level to Expert.

The info_level$ system variable indicates the current setting of the user’sinformation level. The user information level determines how much error informationACCELL/Manager displays when an error occurs.

When application execution begins, ACCELL/Manager initializes the informationlevel to the Novice level. The user can switch between the user information levelswith the �� user command.

As an application developer, you can change the user’s information level byassigning a new user information level to info_level$.

This statement sets the user’s user information level to Expert by assigning a valueof 2 to info_level$.

BEFORE FORMSET info_level$ to 2

“Controlling Form Events” in ��*�� +��“Getting Help” in ��(��

Syntax

LegalValues

Description

Example

See Also


is_current_record_stored$( )


��

(STRING)

TRUE The current record has been stored; used when in add/update/deletemode after the row has been written to the database.

FALSE The current record has not been stored; used when in find mode or inadd/update/delete mode before the row is written to the database.

The is_current_record_stored$( ) system function determines whether the currentrecord has been stored in the database. It returns TRUE when the form is inadd/update/delete mode and the current record has just been written to its associateddatabase row.

The is_current_record_stored$( ) system function reports that the add/update hasoccurred, regardless of whether the transaction was committed or rolled back. Thefunction merely indicates whether the current record was updated in the database.

If this function returns TRUE, an �� command does not affect thecolumn values in the target table row because the current record and the target tablerow are exactly the same.

If the form is in add/update/delete mode but the current record has not been writtento the database, is_current_record_stored$( ) returns FALSE.

If this function returns FALSE, an �� does affect the target table row.After the ��, the target row is updated with the field values in the currentrecord or a new row is added.

This function always returns FALSE when the form is in find mode. It also returnsFALSE after the �� and �� are executed.

This function is useful for determining whether you need to update a database row.

Syntax

ReturnValues

Description


is_current_record_stored$( )

In this example, is_current_record_stored$( ) is used to determine whether adatabase row is associated with the current record. If there is an associated row, thisdatabase row is updated with the field values in the current record.

ON PREVIOUS FORMIF ( NOT is_current_record_stored$() ) THEN


aud_mode$( ), current_record_count$( ), current_record_num$( ),record_is_current$( )

Example

See Also


l_allow_interrupt$( )


�� &��

INFORMIX The l_allow_interrupt$( ) system function is not supported forINFORMIX. Therefore, this function always returns FALSE.

INGRES The l_allow_interrupt$( ) system function is not supported forINGRES. Therefore, this function always returns FALSE.

ORACLE Supported.

SYBASE SQLServer

Supported.

Unify DataServerThe l_allow_interrupt$( ) system function is not supported forUnify DataServer. Therefore, this function always returns FALSE.

interrupt_flag (BOOL) A flag that indicates whether users can interrupt databaseoperations.

TRUE Allow users to interrupt database operations.

FALSE Do not allow users to interrupt database operations.

(BOOL)

TRUE The function succeeded in changing user interrupt capability.

FALSE The function failed to change user interrupt capability. (For example, this can occur when the underlying database does notsupport the feature.)

Syntax

Support

Arguments

ReturnValues


l_allow_interrupt$( )

The l_allow_interrupt$( ) system function specifies whether users can interruptdatabase operations. If interrupt_flag is TRUE and the l_allow_interrupt$( )function completes successfully, users can press the �� key to halt adatabase operation that is in progress.

The �� command affects all ACCELL/SQL database operations. In SYBASESQL Server or ORACLE, some operations wait indefinitely; l_allow_interrupt$( )enables you to avoid the wait or disable interruption.

By default, the interrupt flag is TRUE. That is, unless you call this function todisable interrupts, users can always interrupt database operations.

l_wait_time$( )��(�� !"#��$ ��

Description

See Also


l_wait_time$( )


��

INFORMIX Supported.

INGRES Supported. However, because locking depends on SETLOCKMODE, the results of l_wait_time$( ) do not take effect untilthe current transaction is committed and a new transaction is started.

ORACLE Supported.

SYBASE SQLServer

Supported.

Unify DataServerThe l_wait_time$( ) system function is not supported for theUnify DataServer RDBMS. Therefore, this function always returnsFALSE.

seconds (NUMERIC) The number of seconds to wait for a lock.

(BOOL)

TRUE The argument passed is a valid number.

FALSE The argument passed is not a valid number or this feature cannot becontrolled.

The l_wait_time$( ) function specifies the number of seconds to wait for locks. If alock is not obtained before the specified time expires, ACCELL/Manager assumes thatthe object is already locked and abandons the attempt.

When a lock cannot be obtained for an interactive operation, ACCELL/Managerdisplays an error message that indicates that the record is locked. When a lock cannotbe obtained for a noninteractive operation, the status value SS_LMOUT is returned.

Syntax

Support

Arguments

ReturnValues

Description


l_wait_time$( )

If the number of seconds is zero (0), ACCELL/Manager waits indefinitely. If allowedby the RDBMS, to escape a waiting condition, the user can press the key sequence forthe �� command. ACCELL/Manager assumes that a lock conflict hasoccurred and ceases waiting for the lock.

l_allow_interrupt$( )OSEC2WAIT in �� &�� '�� (��!�&�� !"#��$ ��

See Also


last_command$( )


6��

��

(NUMERIC) A NUMERIC value that indicates the last executed command. Thefollowing table lists ACCELL/Manager commands and the equivalentreturn value name:

.(//7%�� $ ��8��

��

��

��

��

��

��

� ��

� ��

��

��

��

��

��

��

��

��

��

��

��

��

��

��

� ��'��+ ��

!2�3"4&5!2�3 ��6!2�3!172!2�3!58 !2�3!58/!2�3�#0!!2�3/&1�!2�3/0"!!2�3#0"!!2�321!1!2�321�#!2�31/#�!2�31/02!2�310"!!2�31�"5!2�315 9!2�36/#�!2�36/02!2�360"!!2�36�"5!2�365 9!2�37882!2�3�!2�

Syntax

ReturnValues


last_command$( )

The last_command_name$( ) system function returns a numeric value indicating thelast command executed. When checking the last_command$( ) return value, use thereturn value name in your form script.

To use the last_command$( ) function, you must use the ACCELL/SQL preprocessorstatement, #include, to include the header file command.h in your form script. Thisheader file contains definitions for the last_command$( ) return value names. It islocated in the include directory of the ACCELL/SQL release.

This function is useful within an event section that can be initiated by several usercommands. You can use last_command$( ) in the section to determine which usercommand has been executed and perform different actions depending on thelast_command$( ) return value.

The last_command$( ) function does not return a value for commands initiated withthe NEXT ACTION command.

The ON NEXT RECORD section is executed when the user presses �� ,��, or ��. In this example, REJECT OPERATION rejects the�� command. �� or �� commands cause executionof the statements in ON NEXT RECORD. The #include statement includes thelast_command$( ) header file, command.h.

#include ”command.h”...

/* Reject the LAST RECORD command but allow NEXT RECORD and NEXT SET */ON NEXT RECORD

IF ( last_command$() = CMD_LREC ) THENREJECT OPERATION

ELSEDISPLAY ’Moving to next set of records’ FOR FYI_MESSAGE WAIT

DEFINE COMMAND, QUEUE COMMAND, last_command_name$( )

Description

Example

See Also


last_command_name$( )


��

(STRING) A STRING value that indicates the last executed command. Thefollowing table lists return values and the equivalentACCELL/Manager commands:

$ ��8�� (9��1�� .(//7%��

:.++�*;+.-(:

:."(/�<##%:

:/(.$�-#�.++:

:/(.$�-#��!"+:

:+(/(-(:

:(&!-:

:�!"+:

:�!$)-�$(#$+:

:/.)-�$(#$+:

:"(&-��!(/+:

:"(&-��#$%:

:"(&-�$(#$+:

:"(&-�)(-:

:"(&-�-.5:

:;$(8!#*)��!(/+:

:;$(8!#*)��#$%:

:;$(8!#*)�$(#$+:

:;$(8!#*)�)(-:

:;$(8!#*)�-.5:

:<##%:

��

��

��

��

��

��

� ��

� ��

��

��

��

��

��

��

��

��

��

��

��

��

For a developer-defined command, the command_name defined inthe DEFINE COMMAND event section is returned.

Syntax

ReturnValues


last_command_name$( )

The last_command_name$( ) system function returns a string value that indicatesthe last command executed.

This function is useful within an event section that can be initiated by several usercommands. You can use last_command_name$( ) in the section to determine whichuser command has been executed and perform different actions depending on thelast_command_name$( ) return value.

The last_command_name$( ) function does not return a value for user commandsinitiated with the NEXT ACTION command.

In this example, a command is defined that moves the cursor to the next field aftersetting the current field to a default value. The default value is set in the ON FIELDevent section.

FIELD amountINPUTIF (last_command_name$() = ’use_default’) THEN

BEGINSET amount TO 0END

ELSEBEGINIF (amount IS UNDEFINED) THEN

BEGINRESTART ON FIELDEND

END

DEFINE COMMAND ”use_default”AUD_ACTION IS ‘ENABLED’FIND_ACTION IS ’ENABLED’LABEL IS ’F7–USE DEFAULT’KEYS ARE ’None<Key>F7’NEXT ACTION IS NEXT_FIELD

DEFINE COMMAND, QUEUE COMMAND, last_command$( )

Description

Example

See Also


mdy_to_date$( )


�� %��%��

month (NUMERIC) A variable containing the month to be converted to theDATE value. Must be an integer in the range 1 to 12.

day (NUMERIC) A variable containing the day to be converted to theDATE value. Must be an integer in the range 1 to 31.

year (NUMERIC) A variable containing a 2- or 4-digit year number to beconverted to the DATE value.

(DATE)

value The DATE value corresponding to the month, day, and year values.

null_DATE One of the arguments (month, day, or year) was null.

UNDEFINED One of the arguments (month, day, or year) was invalid or undefined.

The mdy_to_date$( ) system function converts three NUMERIC values: month, day,and year to a DATE value. The year must be given as a four digit number. Forexample, you would use 1988 (not 88) for the year 1988.

This function returns a null DATE value if any of the arguments, month, day, or yearwas a null value. It also returns a null DATE if one of these arguments is an invalidvalue. An example of an invalid day is 35. An example of an invalid month is 14.

Syntax

Arguments

ReturnValues

Description


mdy_to_date$( )

In this example, date_to_mdy$( ), mdy_to_date$( ), and current_date$( ) create aDATE variable with a date of five years from the current date.

SET today_date TO current_date$()date_to_mdy$(today_date, month, day, year)SET year TO year + 5SET five_years TO mdy_to_date$(month, day, year)

date_to_mdy$( ), str_to_date$( ), to_date$( )

Example

See Also


null_convert$( )

System function Null value conversion

��1 �� %��&��

value (Any valid type) The expression to be converted to thedefault_value. This expression can be of any ACCELL/SQL datatype.

default_value (Any valid type) The default value to assigned to value if valuecurrently has a null value.

For a null valued valueThe value indicated by default_value.

For a non-null valued valueThe value indicated by value.

The null_convert$( ) system function converts a null value to a valid value. Thisfunction allows you to substitute a non-null value for a null value in an expression.

If the current value of value is the null value, null_convert$( ) returns the valuelisted in default_value. If value is a non-null value, this function just returns value.

For a text value, the default value can be either of type STRING or TEXT.

Syntax

Arguments

ReturnValues

Description


null_convert$( )

In this example, null_convert$( ) ensures that the grade_total variable is neverassigned the null value in the grade calculation. If student_grade is the null value,null_convert$( ) returns the integer zero (0) and the value zero is added tograde_total. If student_grade is not the null value, null_convert$( ) just returns thestudent_grade value and this value is added to grade_total.

SET $grade_total TO$grade_total + null_convert$($student_grade, 0)

str_to_date$( ), str_to_time$( ), str_to_val$( ), val_to_str$( ), to_amount$( ),to_binary$( ), to_bool$( ), to_date$( ), to_float$( ), to_num$( ), to_text$( ),to_time$( )

Example

See Also


open_message_file$( )


�� &��

filename (STRING) A string that contains the full directory path and file nameof the message file to be opened.

(NUMERIC)

0 The message file is successfully opened.

errno The value of the operating system status code errno if the messagefile is not successfully opened.

The open_message_file$( ) system function opens the message file filename. Iffilename is a null string, open_message$( ) produces a runtime error.

Multiple message files can exist. However, only one message file can be open at atime. If another message file is already open, open_message_file closes this messagefile before opening the message file filename.

Messages are stored, one per line, in a special format. For a complete description ofthe message file format, see the description for the ACCELL/SQL system functionget_message$( ).

Syntax

Arguments

ReturnValues

Description


open_message_file$( )

In this example, open_message_file$( ) opens the message file /usr/apps/messages.If this message file can be opened, the code sample retrieves a message from it usingget_message$( ). After the message is retrieved, the message file is closed byclose_message_file$( ).



END

close_message_file$( ), get_message$( )

Example

See Also


os_type$( )


��

(STRING) The name of the operating system on which ACCELL/Manager isbeing executed. The return value is one of the following strings:

DOS The DOS operating system.

UNIX The UNIX operating system.

The os_type$( ) system function enables you to write statements specific to aparticular operating system. os_type$( ) takes no arguments and returns the name ofthe current operating system type as a string.

In this example, the system command that is executed is dependent upon theoperating system type.

IF os_type$() = ’DOS’ THENsystem$(’edlin accell.tmp’)

ELSEsystem$(’vi /temp/accell_file’)

db_type$( ), ui_type$( )

Syntax

ReturnValues

Description

Example

See Also


pad_str_left$( )


�� %��%��

variable (STRING) The string or text value to pad.

pad_str (STRING) The string containing a character with which to pad thevariable value on the left.

str_length (NUMERIC) The requested length of the padded variable value.

(STRING)

The padded string or text of length str_lengthvariable and pad_str are not null or invalid, and str_length is greaterthan variable length.

A null string or textvariable or pad_str is null, or str_length is equal to variable length.

The pad_str_left$( ) function pads the left side of a variable value with the padcharacter in pad_str. If the pad_str contains more than one character, only the firstcharacter of the pad_str.

The variable value is padded on the left until the length of variable value is equal tostr_length. If the str_length is less than the length of the variable argument or ifpad_str is a zero-length string, variable remains unchanged.

Syntax

Arguments

ReturnValues

Description


pad_str_left$( )

In this example, pad_str_left$( ) pads the string in str on the left with the padcharacter x. The final padded string is xxxxxxfour.

SET str TO ’four’

IF ( pad_str_left$(str, ’x’, 10) = ’xxxxxxfour’ ) THENDISPLAY ’Left padded string with length of 10’

FOR FYI_MESSAGE

pad_str_right$( )

Example

See Also


pad_str_right$( )


�� %��%��

variable (STRING or TEXT) The string to be padded.

pad_str (STRING) The string containing the character that pads the string onthe right.

str_length (NUMERIC) The desired length of the padded string.

(STRING)

The padded string or text of length str_lengthvariable and pad_str are not null or invalid, and str_length is greaterthan variable length.

A null string or textvariable or pad_str is null, or str_length is equal to variable length.

The pad_str_right$( ) function pads the right side of a string with the pad characterin pad_str. If the pad_str contains more than one character, the first character of thepad_str is used as the pad character.

The string is padded on the right until the length of string is equal to str_length. Ifstr_length length is less than the length of the string argument or if pad_str is azero-length string, string remains unchanged.

Syntax

Arguments

ReturnValues

Description


pad_str_right$( )

In this example, pad_str_right$() pads the string in str on the right with the padcharacter x. The final padded string is fourxxxxxx.

SET str TO ’four’

IF ( pad_str_right$(str, ’x’, 10) = ’fourxxxxxx’ ) THENDISPLAY ’Right padded string with length of 10’FOR FYI_MESSAGE

pad_str_left$( )

Example

See Also


push_shell$( )


��

None

The push_shell$( ) system function allows the user to access the operating systemcommand line from within an ACCELL/SQL application.

Upon return from the push_shell$( ) function, the screen is automatically repainted.

The type of shell that is executed is determined by the setting of the SHELLconfiguration variable.

To exit this shell, the user types in the shell termination command. This commandvaries depending upon the type of operating system shell.

In this sample, if the user answers Y, push_shell$( ) starts an operating systemprocess.

IF (user_response = ’Y’ ) THENpush_shell$()

system$( )

Syntax

ReturnValues

Description

Example

See Also


�

record_is_current$( )


��

(BOOL)

TRUE There is a current record in the selected set.

FALSE There is no current record (and no selected set).

The record_is_current$( ) system function determines whether there is a currentrecord in the application. On single-occurrence forms, the current record is the targettable row displayed on the form. On multi-occurrence forms, the current record is thetarget table row highlighted by the cursor.

This function returns TRUE as long as the current record has an associated targettable row in the database. If values in the current record have been modified but thesevalues have not yet been stored in the database, record_is_current$( ) still returnsTRUE.

The record_is_current$( ) function returns FALSE after an unsuccessful databasesearch, immediately after a �� command, or when there is a set on aform with no target table.

In this example, the record_is_current$( ) system function is used to determinewhether the form has a current record. If there is no current record, the user is notallowed to continue to the next form in the application.

ON NEXT FORMIF NOT record_is_current$() THEN

REJECT OPERATION

current_record_count$( ), current_record_num$( ), is_current_record_stored$( )

Syntax

ReturnValues

Description

Example

See Also



System function String or text comparison

��

variable (STRING/TEXT) The string to be compared.

mask (STRING) A mask containing the regular expression.

(BOOL)

TRUE variable value contains the segment specified by the mask.

FALSE variable value does not contain the segment specified by the mask;or the mask or the variable value is a null string.

The reg_exp_str_compare$( ) system function compares a variable value with aspecial string mask which specifies valid string segments. If variable value contains astring that matches any of the segments described by the mask,reg_exp_str_compare$( ) returns a BOOL value of TRUE.

With reg_exp_str_compare$( ), you use regular expression notation to create apattern mask. The mask contains a regular expression that defines valid segmentpatterns.

All ordinary characters (all characters except ., *, [, ], {, }, and \) match themselves.Because the backslash (\) character is an ACCELL/4GL escape character, a backslashwithin a regular expression must be preceded by a backslash.

Syntax

Arguments

ReturnValues

Description


�



��

��

��


The following table defines the regular expression metacharacters.

��

Symbol Specifies Example Specifies a Segment

. Any single character ABC. Four characters long andstarting with ABC: forexample, ABCD, ABCE,ABC1, and so on.

* The previous regularexpression zero or moretimes

A*C Containing zero or moreoccurrences of A followed byC: for example, C, AC, AAC,AAAAAAC, and so on.

\ Literal character (exceptdigits)

\ \ Containing the character \.

^ Beginning of the string ^The Containing the word Theoccurring at the beginning ofthe string.



Symbol Specifies Example Specifies a Segment

$ End of the string end$ Containing the word end atthe end of the string.

[ ] Any character specifiedwithin the brackets

[ABCD] Containing one of the values:A, B, C, or D.

� �� !� �

[^abc] Containing any characterexcept a, b, or c.

" � ��

[a–z] Containing any lower caseletter.

\{m,n\} The previous regularexpression occurring at leastm times and not more than ntimes anywhere in the string.

! "#�� $ ��$��%��&��

a\\{3\\} Containing aaa

!� "#�� $ ��&��&��

a\\{3,\\} Containing aaa, aaaa, oraaaaaa, and so on

!� "#�� $ ��&��&�� &��

a\\{3,5\\} Containing aaa, aaaa, oraaaaa

$r$ . . . \n

The regular expression that isthe nth grouped regularexpression enclosed in \$ and\$.

\$A\$B\$C\$D\\2

Containing ABCDC


�


The glob_str_compare$( ) system function also provides string comparison with amask. However, usually, the regular expression notation ofreg_exp_str_compare$( ) function provides a more complete string specificationnotation that greatly exceeds the capability of glob_str_compare$( ).

In this example, the reg_exp_str_compare$( ) system function is used to check theformat of a telephone number. The mask verifies that the number has three digits,followed by a hyphen (–), followed by four more digits. This mask is the secondargument of reg_exp_str_compare$( ).

FIELD phoneON FIELD

INPUTIF ( reg_exp_str_compare$(phone, ’[1–9]\\{3\\}–[0–9]\\{4\\}’) )THEN

DISPLAY ’Valid phone number format!’FOR FYI_MESSAGE WAIT

ELSEBEGIN

DISPLAY ’Invalid phone number format! Try Again.’FOR FYI_MESSAGE WAIT

RESTART ON FIELDEND

If the phone variable has a valid format, a message appears:

Valid phone number format!

If the phone variable does not have a valid telephone number format, the user isnotified of the error, and input is restarted.


Example

See Also


serve_message$( )

System function Process control

'�#��$��%&�(

��'��

execname (NUMERIC) Code that indicates the name of the file to be executed:

)��%&��)�� $��

( )*��+, �))�**+�,*��& ��

- )*��,./ �))�**+�,*�*��

0 )*��*12 �))�**+#��

3 )*��*� �))�**+)�&��

4 )*�)5 ��

6 )*�78 ��

9 )*��1:. �))�**+-��

; )*�.<):= ��

> )*�?0�0? �))�**+�,*�@0�0@��%

A )*�*/*�B */�+��%

To use the symbolic constant instead of the code, include thesmcodes.h file.

Syntax

Arguments


�

serve_message$( )

opcode (NUMERIC) Code that indicates the operation the executable is toperform:

)��%&��)�� . ��

( )*�:C8D �$��&&��

- )*�:C:� �$��&&��

0 )*��5=82 )��%

3 )*��5�+D5 )��&&��/��)*��5�+D5�� &��

To use the symbolic constant instead of the code, include thesmcodes.h file.

cmdstr (STRING) Text of the command to be sent to the executable. Forexample, this statement calls vi to edit two files named file1 andfile2:

. . . serve_message$(SM_VI, SM_EXEC, ’file1, file2’, . . .)

silent (BOOL) Output display flag. The silent option is valid only inCharacter mode. If silent is TRUE, no output is displayed. If silent isFALSE, output is displayed as the command executes.

result (NUMERIC) Exit status of the program called: a zero value (0)indicates that the called program executed successfully, while anonzero value indicates that the program failed.

(NUMERIC) The failure status of the program call:

0 A zero value indicates that the called program was startedsuccessfully.

nonzero A nonzero value indicates that the call was unable to start theprogram.

ReturnValues


serve_message$( )

The serve_message$( ) system function starts and stops executables in a subprocessand can send commands to the subprocess for certain executables. In the followingtable, a plus sign (+) indicates the operations that can be performed with eachexecutable. To reference the symbols listed in this table, include the smcodes.h file.The smcodes.h file is located in the include directory of the release directory.

�$��. ��)��

�$��&�

)*�:C8D� )*�:C:�� )*��5=82 �)*��5�+D5

�)*��+, � 0 � �

�)*��,./ � 0 � �

�)*��*12 0 0 0 0

�)*��*� � 0 � �

�)*�)5 � 0 � �

�)*�78 � 0 � �

�)*��1:. 0��&��%!

00

��&��%!

�

�)*�.<):=

��

�)*�?0�0? � 0 � �

�)*�*/*�B � 0 � �

In character mode applications, ACCELL/Manager and ACCELL/Generator processesremain present until the application is exited.

Description


�

serve_message$( )

The first half of this sample is similar to the code that Menu Handler uses to callACCELL/Manager to run an application. The second half of the example tellsACCELL/Manager to quit.

#include ”smcodes.h”��

/* start ACCELL/Manager */SET $command TO ’tutorial.al’ ;SET $result TO

serve_message$(SM_AMGR,SM_EXEC,$command,FALSE,$stat);IF $result <> 0 AND $stat <> 0 THEN

DISPLAY ’Could not execute ACCELL/Manager’ FOR FYI_MESSAGE WAIT;

��

/* terminate ACCELL/Manager */SET $command TO ’tutorial.al’ ;SET $result TO

serve_message$(SM_AMGR,SM_EXIT,’’,FALSE,$stat);IF $result = 0 THEN

DISPLAY ’ACCELL/Manager has been terminated’ FOR FYI_MESSAGE WAIT;

Example


set_button_color$( )

System function: presentation User interface dependent

��$��

The set_button_color$( ) system function is supported for graphical user interfacesonly.

command_name (STRING) Name of a user-defined command on the current form(not a widget name).

color_resource (STRING) Name of a color resource recognized by the�))�**+�,* Motif or OPEN LOOK UI option. This argument iscase-sensitive and must be specified exactly as shown in thefollowing list:

Valid Motif UI color resources:backgroundforegroundhighlightColorborderColortopShadowColorbottomShadowColor

Valid OPEN LOOK UI color resources:backgroundforegroundhighlightColorborderColorfontColor

new_color (STRING) If the color is not available, an attempt is made to convertto the nearest color. For example, if you specify blue or yellow on ablack and white terminal, blue may be converted to black, andyellow to white.

Syntax

Support

Arguments


�


(NUMERIC)

0 The function was successfully completed.

1 All arguments were correct and the call was sent to change the color.A return of 1 does not ensure that the color was changed. Forexample, the color cannot be changed if an invalid value is given.

2 Invalid arguments were given. For example, the wrong number ofarguments or the wrong type of arguments was specified.

3 An invalid command name was specified; the command could not befound on the current form.

4 An invalid color resource name was specified. For example, anOPEN LOOK UI color resource was specified for Motif mode.

5 All arguments were valid, but the call to change the color failed.This can happen if the color is not in the ColorMap database.

You can use the error return to determine whether an error occurred. However, noerror message is displayed if the set_button_color$( ) system function is usedincorrectly.

The set_button_color$( ) system function dynamically changes a color resource for adeveloper-defined button on an �))�**+�,* form being used with the Motif orOPEN LOOK UI option. The function changes the button color resource to a newcolor and returns a numeric value that indicates the success of the function. Eachbutton is represented by a widget (user interface object) on the screen. Each widgetcan have resources identified for it, for example, background color.

ReturnValues

Description



The following script changes the foreground color used in the print button pr_btn togreen if the user has just completed a find operation:

BUTTON pr_btn

AFTER FIND IF set_button_color$(’pr_btn’, ’foreground’, ’Green’) <> 0THEN DISPLAY ’set_button_color function has failed.’

FOR FYI_MESSAGE WAITELSE

DISPLAY ’Press PRINT button to print report.’FOR FYI_MESSAGE WAIT

END

�� !"#�$�%�� &�� '��(��)��*��+ ��'��

Example

See Also


�

set_cursor_mem_limit$( )

System function: process control RDBMS dependent

��$�� ,��

INFORMIX The set_cursor_mem_limit$( ) system function is not supported forINFORMIX. Therefore, this function returns FALSE.

INGRES The set_cursor_mem_limit$( ) system function is not supported forINGRES. Therefore, this function returns FALSE.

ORACLE The set_cursor_mem_limit$( ) system function is not supported forORACLE. Therefore, this function returns FALSE.

SYBASE SQLServer

Supported.

Unify DataServerThe set_cursor_mem_limit$( ) system function is not supported forUnify DataServer Therefore, this function returns FALSE.

maxbytes (NUMERIC) Maximum number of bytes stored in memory for eachselected set created by a nested query.

If maxbytes is 0 or less than the number specified by theACLVARMEMLIM configuration variable, then the amount of memorythat is used for each selected set is set to the value ofACLVARMEMLIM.

If maxbytes is greater than the value of ACLVARMEMLIM, then theamount of memory that is used for each selected set is set tomaxbytes.

(BOOL)

TRUE The memory limit was successfully set.

FALSE The maxbytes argument is invalid or the database system supportsmultiple cursors.

Syntax

Support

Arguments

ReturnValues


set_cursor_mem_limit$( )

The set_cursor_mem_limit$( ) system function overrides the default memory limitspecified by the DFLTVCMEM configuration variable for selected sets created bynested queries. ACLVARMEMLIM specifies the number of bytes to be used to storevariable-length data (TEXT and BINARY) in memory. When the limit would beexceeded, the rest of the rows are placed on disk. If this function is not called, thedefault limit is specified by the DFLTVCMEM configuration variable.

DFLTVCMEM in �� !"#�$�� '�&�� -�� *��,�.�'�� !"#�$�.%/0"�+ ��&��

Description

See Also


�

set_field_color$( )

System function: presentation User interface dependent

��$��$�� ''�� E('��

The set_field_color$( ) system function is supported for graphical user interfacesonly.

form_name (STRING) The name of an active form.

field_name (STRING) The name of a field on the current form if the form_nameargument is not included. If form_name is included, then field_nameis the name of a field on the specified form. For a LIST or MATRIXfield, the array index must be expressed as a string or as aself-reference, for example, daily_expense[1,1] or daily_expense[].The array index cannot be expressed as a variable.

color_resource (STRING) The name of a color resource recognized by the�))�**+�,* Motif or OPEN LOOK UI option. The color resourcename, which is case sensitive and must be specified exactly asshown, may be one of these:

Valid Motif UI color resources:

��F��

��

&��&$��&��$��

��$��

��)&��G��$��

��)&��G��$��

Valid OPEN LOOK UI color resources:

��F��&��&$��&��$��

��$��$��

new_color (STRING) A valid color value for this machine, for example, black,white, or green. If the color is not available, an attempt will be madeto convert to the nearest color. For example, if you specify blue oryellow on a black and white terminal, blue may be converted toblack, and yellow to white.

Syntax

Support

Arguments


set_field_color$( )

(NUMERIC) Indicates the success of the function:

0 (NORMAL) All arguments were correct and the call was issued to change thecolor value. (This does not guarantee that the color was changed; forexample, the color could not be changed if an invalid value weregiven.)

1 Invalid arguments were given, for example, the wrong number of orthe wrong type of arguments.

2 ACCELL/Manager is in character mode: the set_field_color$( )function is not valid in character mode.

3 An invalid field name was given: the field could not be found on thecurrent form, or if another active form was specified, the field couldnot be found on the specified form.

4 An invalid color resource name was given; for example, a Motifcolor resource was specified for the OPEN LOOK UI option.

5 All arguments were valid, but the call to change to the new colorfailed. This can happen if the color is not in the ColorMap database.The call to change the color can also fail when using the OPENLOOK UI option, if a Toolkit bug prevents the setting of theinputFocusColor resource.

No error message is displayed if the system function is used incorrectly. You canexamine the error return to determine whether an error occurred.

The set_field_color$( ) system function sets a color resource for a field to a newcolor value and returns a numeric value that indicates the success of the function. Thefunction can fail because of a wrong number of or invalid arguments, because of aninvalid field name, or because of an unknown color value for the specified colorresource. Only a predefined set of color resource names are valid (see Arguments).

ReturnValues

Description


�

set_field_color$( )

The following script changes the foreground color used in the company name field,co_name, to green if the company’s next contact is scheduled for today.

FIELD co_name

BEFORE FIELDIF current_date$() = leads:ld_next_date THENBEGIN

IF set_field_color$(’co_name’, ’foreground’, ’Green’) <> 0 THENDISPLAY ’set_field_color function failed’ FOR FYI_MESSAGE WAIT

ELSEDISPLAY ’Contact company today’ FOR FYI_MESSAGE WAIT

END

�� !"#�$�%�� &�� '��(��)��*��+ ��'��

Example

See Also


set_interrupt$( )


�� '��&��

interrupt_flag (BOOL) A flag that determines whether the keyboard interrupt isenabled.

(BOOL)

TRUE (Default) The keyboard interrupt is enabled.

FALSE The keyboard interrupt is disabled.

The set_interrupt$( ) system function determines whether the interrupt key isenabled. The effect of the keyboard interrupt key on the database is dependent uponthe RDBMS.

This SET statement uses set_interrupt$( ) to disable the interrupt key.

SET interrupt_key TO set_interrupt$(FALSE)

�� !"#�$�*� &�� !"#�$��,�(�� !"#�$�.%/0"�+ ��&��

Syntax

Arguments

ReturnValues

Description

Example

See Also


�

show_dirty$( )


&�G��H ��)��,�'��&��

INFORMIX Does not support show_dirty_data option. The INFORMIX RDBMSalways reads dirty data. This function always returns TRUE.

INGRES Does not support show_dirty_data option. The INGRES RDBMSalways reads dirty data. This function always returns TRUE.

ORACLE Does not support show_dirty_data option. The ORACLE RDBMSalways reads dirty data. This function always returns TRUE.

SYBASE SQLServer

Does not support show_dirty_data option. Sybase doesnot allow access to dirty data. This function alwaysreturns FALSE.

Unify DataServerSupports show_dirty_data option. The Unify DataServer RDBMSallows or disallows dirty data to be read on the basis of theshow_dirty_flag setting.

show_dirty_flag(BOOL) A flag you can set to specify whether dirty data is to beread.

(BOOL)

TRUE If the RDBMS supports this option, TRUE indicates that the attemptto set the show_dirty_data flag successful.

FALSE If the RDBMS supports this option, FALSE indicates that theattempt to set the show_dirty_data flag failed.

Syntax

Support

Arguments

ReturnValues


show_dirty$( )

The show_dirty$( ) system function is used to specify whether the application canread dirty data. Dirty data is data taken from a database row that is exclusive-lockedby another transaction.

If a row is exclusive-locked, it is usually because some other transaction is updating,deleting, or adding the row. The data in this exclusive-locked row may be beingupdated or deleted by another transaction. The exclusive-locked row may not havethe same column values in the database when the exclusive lock is released. If therow has been deleted, the values may not even exist.

To allow dirty data within your application, set show_dirty_flag to TRUE. Thedatabase can then access dirty data.

To prevent dirty data from being used in your application, set show_dirty_flag toFALSE. The show_dirty$( ) function tells the database not to send dirty data to theapplication. If the application is not allowed to read dirty data, no column values forexclusive-locked rows are selected from the database.

If the application is not allowed to read dirty data, no exclusive-locked rows will beread by the database. During a database search, exclusive-locked rows will not beselected.

If the RDBMS supports the ACCELL/SQL system function check_dirty$( ), you candetermine whether any exclusive-locked rows were accessed during a search, eventhough these rows are not selected.

show_dirty$( ) has no effect in set consistency: no locked records are read. In recordconsistency, if show_dirty$( ) is set to FALSE, UNDEFINED records are created.

DependenciesUnify DataServer. If the application is not allowed to access dirty data (that is, theshow_dirty_data flag is set to FALSE), the following conditions occur:

The column values in the exclusive-locked rows are not to be selected from thedatabase. These values are UNDEFINED within the application.

The status$( ) system function returns a status of 0 if no exclusive-lockedrows were encountered and returns a status of SS_LMOUT if exclusive-lockedrows were encountered.

�

Description


�

show_dirty$( )

This SET statement uses show_dirty$( ) to allow the current application to read dirtydata. If the database can access dirty data, the BOOL flag ck_data is TRUE and theapplication will show dirty data. If the database cannot access dirty data, ck_data isFALSE.

SET ck_data TO show_dirty$(TRUE)

check_dirty$( )�� !"#�$�.%/0"�+ ��&��

Example

See Also


sleep$( )


$��

seconds (NUMERIC) The number of seconds to suspend execution ofACCELL/Manager (and the application).

None.

The sleep$( ) system function suspends the application execution for the number ofseconds in seconds. This function tells ACCELL/Manager to call the C libraryfunction sleep( ).

Additional HelpFor more information about sleep( ), refer to your operating system referencemanuals.

This example uses sleep$( ) to pause execution of the application after displaying aninitial message “Welcome to the ACCELL/SQL Application”.

DISPLAY ’Welcome to the ACCELL/SQL Application’FOR FYI_MESSAGE

sleep$(10)

This usage of the sleep$( ) function performs almost the same task as the WAITclause of the DISPLAY statement. In this case, however, the user does not need topress �� to continue execution.

Syntax

Arguments

ReturnValues

Description

Example


�

sp_compute$( )


��

INFORMIX The sp_compute$( ) system function always returns FALSE becauseINFORMIX stored procedures never contain a COMPUTE clause.

INGRES The sp_compute$( ) system function always returns FALSE becauseINGRES database procedures never contain a COMPUTE clause.

ORACLE The sp_compute$( ) system function always returns FALSE becausestored procedures are not supported.

SYBASE SQLServer

Supported.

Unify DataServerThe sp_compute$( ) system function always returns FALSE becausestored procedures are not supported.

None

(BOOL)

TRUE The retrieved row is the result of a COMPUTE clause.

FALSE The retrieved row is not the result of a COMPUTE clause.

The sp_compute$( ) system function determines whether the recently returned row isthe result of a COMPUTE clause in a SYBASE SQL Server SELECT statement.

Syntax

Support

Arguments

ReturnValues

Description


sp_compute$( )

The following example determines whether $var1 and $var2 are set to resultsreturned by a COMPUTE clause in a SELECT statement.

SET $var1, $var2, $var3, $var4, $var5 TO stored_proc()EXECUTING SWITCH sp_select$()

BEGINCASE 1:

/* $var1 contains value returned by SELECT #1 */. . .

CASE 2:IF (sp_compute$()) THEN/* $var1 and $var2 contain values returned by COMPUTE clause */

. . .ELSE/* $var1, $var2, and $var3 contain values returned by SELECT #2 */

. . .CASE 3:

/* $var1, $var2, $var3, $var4, and $var5 contain values *//* returned by SELECT #3 */

. . .END

EXTERN, SETsp_return$( ), sp_select$( )�� !"#�$�.%/0"�+ ��&��

Example

See Also


�

sp_return$( )


��

INFORMIX The sp_return$( ) system function always returns FALSE becauseINFORMIX stored procedures always return a fixed number ofelements.

INGRES Supported.

ORACLE The sp_return$( ) system function always returns FALSE becausestored procedures are not supported.

SYBASE SQLServer

Supported.

Unify DataServerThe sp_return$( ) system function is not supported forUnify DataServer. Therefore, this function returns FALSE.

None.

(NUMERIC)

0 For INGRES, the database procedure was successfully completed butdid not contain the RETURN statement, or the database proceduredid not complete successfully. For SYBASE SQL Server, the storedprocedure was successfully completed, but did not contain theRETURN statement.

–1 through–99

Error codes that are reserved by SYBASE SQL Server to indicatewhy the stored procedure was not successfully completed.

return value The value returned by a stored procedure or database procedurewhen execution has been completed and the procedure contains theRETURN statement.

Syntax

Support

Arguments

ReturnValues


sp_return$( )

The sp_return$( ) system function obtains the return status of the last call to a storedprocedure. sp_return$( ) can be used after execution of the stored procedure iscompleted. At each loop through the SET statement EXECUTING block, the returnstatus is reset to UNDEFINED. When the procedure execution is completed, thereturn status is set to the return status of the stored procedure.

In the following example, a NUMERIC stored procedure named sp_limit( ) returns 1when a customer’s charge is greater than the account limit and returns 0 when thecharge is less than the limit.

SET $acct_stat TO sp_limit($cust_ID,$charges);

The same results are also returned by the following statements:

sp_limit($cust_ID,$charges);

SET $acct_stat TO sp_return$();

In the following example, a ROW_VALUED stored procedure named sp_items isused in place of a SET . . . SELECT statement. The sp_items stored procedureselects data from a table named items, where each selected row has an item costgreater than the argument passed to sp_items. When execution of the storedprocedure is completed, the number of rows found is returned in the return value.

The stored procedure definition for sp_items( ) contains these SYBASE SQL Serverstatements:

CREATE PROC sp_items @cost moneyASDECLARE @cnt intSELECT item_key, item_costFROM items

WHERE item_cost > @cost

SELECT @cnt = count(*)FROM items

WHERE item_cost > @cost

RETURN @cnt

Description

Example


�

sp_return$( )

First the sp_items stored procedure is declared in an EXTERN statement:

EXTERN STORED ROW_VALUED FUNCTION sp_items(ge_value) ;

Then sp_items( ) is called in the ACCELL/4GL script by using the followingstatements:

SET $cnt TO 0 ;

SET $key, $item_cost TO sp_items(100.00)EXECUTINGBEGIN

/* Process $key and $item_cost here */END

SET $cnt TO sp_return$()

EXTERN, SETsp_compute$( ), sp_select$( )�� !"#�$�.%/0"�+ ��&��

See Also


sp_select$( )


��$��

INFORMIX The sp_select$( ) system function always returns 1 becauseINFORMIX stored procedures always return a fixed number ofelements.

INGRES The sp_select$( ) system function always returns 1 because INGRESdatabase procedures always return a fixed number of elements.

ORACLE The sp_select$( ) system function always returns FALSE becausestored procedures are not supported.

SYBASE SQLServer

Supported.

Unify DataServerThe sp_select$( ) system function always returns FALSE becausestored procedures are not supported.

None.

(NUMERIC)

1 or higher The index of the current SELECT in the stored procedure. The firstSELECT returns 1; the second SELECT returns 2; and so on.

Syntax

Support

Arguments

ReturnValues


�

sp_select$( )

The sp_select$( ) system function determines which of a stored procedure’s SELECTstatements is currently being executed. You can use this function when your storedprocedure contains multiple SELECT statements, and you want to perform specifictasks based on the SELECT statement executed. You can use the sp_select$( ) systemfunction anywhere you would use an expression.

The following example uses the sp_select$( ) system function to determine whichSELECT statement generated the last values returned from the stored procedurestored_proc( ).

SET $var1, $var2, $var3, $var4, $var5 TO stored_proc()EXECUTING SWITCH sp_select$()

BEGIN

CASE 1:/* Values in $var1 through $var5 are returned by SELECT #1 */

. . .

CASE 2:/* Values in $var1 through $var5 are returned by SELECT #2 */

. . .CASE 3:

/* Values in $var1 through $var5 are returned by SELECT #3 */. . .END

EXTERN, SETsp_compute$( ), sp_return$( )�� !"#�$�.%/0"�+ ��&��

Description

Example

See Also


sql_clear$( )


@$��$�� I�

(BOOL)

TRUE All commands have been cleared from the buffer.

FALSE The buffer could not be cleared or closed.

The sql_clear$( ) system function closes and clears all buffered commands. Use thisfunction whenever database objects, such as a schema or table, are changed by DDLstatements, or to free memory after commands that will not be executed again.

You need not use this statement with DDL statements that cause automatic clearing:ALTER, CREATE, GRANT, and REVOKE.

This example uses the sql_clear$( ) function to clear all buffered commands after atable view has been dropped.

DROP VIEW high_salary;sql_clear$()

Syntax

ReturnValues

Description

Example


�

sql_code$( )


@$��

(NUMERIC) Value of the sqlcode return field for embedded SQL.

The sql_code$( ) system function returns an integer status field. The values returnedare specific to each RDBMS.

If the RDBMS does not provide an SQL code value, the function returns NULL.

The sql_code$( ) function is provided for compatibility with existing RDBMSproducts only and is not recommended for use with new applications. For newapplications, use the sql_state$( ) function instead.

In this example, an error message is displayed if the UPDATE operation is notsuccessful.

UPDATE emp SET salary = salary * 1.1IF (sql_code$()<> UENOERR

DISPLAY ’Update failed’ FOR FYI MESSAGE WAIT

sql_errmsg$( ), sql_state$( ), dbms_status$( ), status$( )Database error code documentation supplied by the RDBMS vendor

Syntax

ReturnValues

Description

Example

See Also


sql_errmsg$( )


@$�� I�

(STRING) The error message returned as a result of execution of the last SQLcommand, up to a maximum of 2048 characters.

The sql_errmsg$( ) system function returns the error message that corresponds to thelast SQL statement executed. The messages returned are specific to each RDBMS.

This example displays the RDBMS message when any error occurs in the database.

SET emp_name TO SELECT name FROM employee WHERE emp_num = $emp_id;IF dbms_status$() <> NORMTHEN

DISPLAY ’RDBMS Message: ’ + sql_errmsg$()FOR FYI_MESSAGE WAIT

dbms_status$( ), sql_code$( ), sql_state$( ), status$( )�� !"#�$�.%/0"�+ ��&�� Database error code documentation supplied by the RDBMS vendor

Syntax

ReturnValues

Description

Example

See Also


�

sql_errmsg_count$( )


@$�� I�

INFORMIX The sql_errmsg_count$( ) function always returns NULL becausethe function is not supported for this RDBMS.

INGRES The sql_errmsg_count$( ) function always returns NULL becausethe function is not supported for this RDBMS.

ORACLE The sql_errmsg_count$( ) function works exactly as described.

SYBASE SQLServer

The sql_errmsg_count$( ) function always returns NULL becausethe function is not supported for this RDBMS.

Unify DataServerThe sql_errmsg_count$( ) function always returns NULL becausethe function is not supported for this RDBMS.

None

num_msgs (NUMERIC) The number of messages that are contained in the errormessage string that was generated by the last call to the database.

The sql_errmsg_count$( ) function returns the number of error messages that weregenerated by the last database operation that generated a call to the server. Such adatabase operation is initiated by either ACCELL/Manager or a developer-defined Cfunction.

FOR (SET inx TO 1; inx < sql_errmsg_count$(); SET inx TO inx + 1) BEGIN DISPLAY sql_errmsg_i$(inx) FOR FYI_MESSAGE WAIT END

sql_errmsg_i$( ), dbms_status_i$( )

Syntax

Support

Arguments

ReturnValues

Description

Example

See Also


sql_errmsg_i$( )


@$��

INFORMIX The sql_errmsg_i$( ) function always returns NULL because thefunction is not supported for this RDBMS.

INGRES The sql_errmsg_i$( ) function always returns NULL because thefunction is not supported for this RDBMS.

ORACLE The sql_errmsg_i$( ) function works exactly as described.

SYBASE SQLServer

The sql_errmsg_i$( ) function always returns NULL because thefunction is not supported for this RDBMS.

Unify DataServerThe sql_errmsg_i$( ) function always returns NULL because thefunction is not supported for this RDBMS.

index Index, ranging from 1 to n, that indicates the message in the errormessage string that was generated by the last call to the database.

err_msg_string (STRING) The text of the index-indicated error message in the errormessage string that was generated by the last call to the database.

NULL The index value is out of range, or the underlying RDBMS is notORACLE Version 7.

The sql_errmsg_i$( ) function returns the text of the index-indicated error messagein the error message string that was generated by the last database operation thatgenerated a call to the server. The database operation can be initiated by eitherACCELL/Manager or a developer-defined C function.

Syntax

Support

Arguments

ReturnValues

Description


�

sql_errmsg_i$( )

Make sure that if you call the sql_errmsg_i$( ) function, you do so immediately afteryou call sql_errmsg_count$( ). Make sure that you do not generate any additionalcalls to the server between the calls to sql_errmsg_count$( ) and sql_errmsg_i$( ).

FOR (SET inx TO 1; inx < sql_errmsg_count$(); SET inx TO inx + 1) BEGIN DISPLAY sql_errmsg_i$(inx) FOR FYI_MESSAGE WAIT END

sql_errmsg_count$( ), dbms_status_i$( )

Example

See Also


sql_state$( )


@$��

(NUMERIC) Value of the sqlstate field of the SQL communications area.

The sql_state$( ) system function returns a six-character SQL status field. The firsttwo characters are the character class code. The next three characters are the charactersubclass. The last character is a null terminator. The values returned are specific toeach RDBMS.

If the RDBMS does not provide an SQL state value, the function returns NULL.

Note that the sql_state$( ) system function is not supported for ORACLE databases.

In this example, the fyi_message system information field displays a message if theemp table no longer exists in the database.

UPDATE emp SET vacation = vacation + 1IF (sql_state$() = ’30500’)

DISPLAY ’emp table not found’ FOR FYI MESSAGE WAIT

dbms_status$( ), sql_code$( ), sql_errmsg$( ), status$( )�� !"#�$�.%/0"�+ ��&�� Database error code documentation supplied by the RDBMS vendor

Syntax

ReturnValues

Description

Example

See Also


�

status$( )


#��$��%&

��

(NUMERIC)

� 0 An error has occurred and the operation was not successful.

SS_NORM The database operation was successful (status code = 0).

For a complete list of status$( ) return values, see the table following the functiondescription.

The status$( ) system function obtains the success of certain ACCELL/SQLoperations: SQL statements, database operations, CREATE PIPELINE, RETRIEVE,and STORE statements. When checking the status$( ) return value, use the returnvalue names from the sscodes.h file in your form script.

To use the status$( ) function, you must use the ACCELL/SQL preprocessorstatement #include to include the sscodes.h header file in your form script. Thisheader file contains definitions for the status$( ) return value names. It is located inthe include directory of the ACCELL/SQL release.

Use this function to verify the success or failure of the most recent operation. Withstatus$( ), you can check the status of database statements such as INSERT,SELECT, DELETE, UPDATE, SLOCK, and XLOCK.

The status return numbers correspond to the following status return values:

Positive Integers

1 ��234��5

6 ��2�.) 7

8 ��247)�5

9 ��27/��)

: ��2�.);

< ��2�.��5

= ��2> .#.

Syntax

ReturnValues

Description


status$( )

Negative Integers

"1 ��2�7*�?

"6 ��2344.#

"8 ��24;>3?

"9 ��24;>@

": ��27*)

"< ��27*.>�

"= ��2@�A ,

"B ��2/�?�

"C ��2#D�)�

"11 ��2�. �7

"16 ��2�.?;>

"19 ��2 4�)�

"1: ��2 �7

"1< ��2 #�#

"1B ��2�?7;*

"1C ��2E �)�

"6F ��2�A��

"61 ��27/��

"66 ��2;>4��

"68 ��24�*��

"69 ��2�44��

"6: ��2�.#�#

"6< ��24/ ?

"6= ��2�.7/*

"6B ��27*�)�

"6C ��27*�@

"8: ��2�. �)

"8C ��2�#;>

"9F ��2�#4�*

"98 ��2�.*)@

"99 ��2�#*)@

"9: ��2*#.;?

"9< ��2;��

"9= ��2;4743

"9B ��2�6;

"9C ��234�)�

":F ��2�/#>

":6 ��234��*

":8 ��243?A>

":9 ��243*��

":: ��2)#37

":< ��27;�/>

":= ��2).�5

":B ��2�.�)�

":C ��2�.?/4

"<F ��2�. /4

"<1 ��234��#

"<C ��2>� ?

"=F ��2/**�

"=1 ��2�.43

"=9 ��2�.47

"=: ��247�

"=< ��2�.5�*

"== ��2/*?�?

"=B ��2�.)#3

"=C ��2�.�;*

"BF ��22�?*)@

"B6 ��2?D/*

"B8 ��27*)*

"B9 ��23?.>�

"B: ��23?�

"B< ��2G@�

"B= ��2�.4�#

"BC ��2*#/�?

"CF ��2�.�G#

"C1 ��2�G#5

"C6 ��2�.�?

"C8 ��25 �/.�

"C9 ��243)*�

"C: ��2�.*.-

"C< ��2 7*4

"C= ��243#.4

"CB ��2;�5/�E

"CC ��243/�?

"1FF ��2.5 7*E

"1F8 ��243 ��

"1F9 ��2��?�

"1F: ��24��4*)@

"1F< ��2*.-.77

"1F= ��2�*.-7;*

"1FB ��2).*�>�)

"1FC ��2��?�##

"11F ��2436�

"111 ��2 4.�*A

"116 ��2;4�

"118 ��2;4� 3

"119 ��2� .5

"11: ��24/5H

"11< ��2�*�D>

"11= ��2G>#�#

"11B ��2;�4�)*


�

status$( )

The following list describes the meaning of each return value.

Return Status Description

SS_ADDNA Add operation not allowed on form.

SS_AFLST Bad DIS list found performing an add/update operation.

SS_AROVR An arithmetic overflow has occurred.

SS_BDDOM Domain check failed.

SS_BDENV Bad format in configuration variable.

SS_BDNAM Match item has wrong selection file name.

SS_BDSCN Scan identifier is not found.

SS_BDSEL Attempt to enter search item in selection table failed.

SS_BTERR Fatal error in B-tree access; rebuild B-tree.

SS_BTOPN Error opening B-tree.

SS_CMBF Column group not allowed.

SS_COLSPEC Invalid column specification.

SS_CONV atoxx: Internal conversion error.

SS_DBCLS Could not close the database.

SS_DBINT Internal database error.

SS_DBLEN Bad RDBMS length.

SS_DBMOD Database has been modified.

SS_DBRES Out of some database resource.

SS_DBTYP Unknown RDBMS type.

SS_DEADLCK Deadlock encountered; transaction aborted.

SS_DELNA Delete operation not allowed on form.

SS_DFCNV Default value conversion error.

SS_DFERR Error in retrieving default value for a column on insert for column with avalue that is not specified.

SS_DIRT Returned data may be dirty. It was read without first obtaining a lock.

SS_DIVZ Attempted division by zero.

SS_DUPBT Duplicate found in NODUPS B-tree while adding a row.

SS_DUPK Attempt to store a duplicate key.

SS_EOSCN End of scan (rows not found).


status$( )


SS_FINAC Column inaccessible.

SS_FINNA Find operation not allowed on form.

SS_FLACS Denied access to file.

SS_FLCL Failed to close a file.

SS_FLCR Error creating file.

SS_FLOPN Unable to open sort/merge file.

SS_FLSK File seek error.

SS_FUNIP Tried to free a NIL pointer to a database value.

SS_HKERR Hand table entry error.

SS_HPMEM No heap memory is available.

SS_ILLA Illegal argument encountered.

SS_ILTST Illegal test specified in scan.

SS_INTS Interrupted search.

SS_INVLSP Either the stored procedure was declared as a procedure but wasdefined as a function, or was declared as a function but was definedas a stored procedure.

SS_INVLSPTYP An invalid stored procedure type (for example, ROW_VALUED) wasdeclared.

SS_KEYRQ Key column is required.

SS_LMINT Lock manager initialization failed.

SS_LMOUT Unable to acquire lock due to exclusive lock conflict.

SS_LOGFUL The SYBASE SQL Server transaction log table (syslogs) is full.

SS_LOGOFF Transaction logging is not enabled.

SS_MDNTMCH The parameter mode specified in the stored procedure declarationdoesn’t match the parameter mode in the stored procedure definition.

SS_MXSCN Too many active scans.

SS_NETER Network error encountered.

SS_NIMP Feature not implemented.

SS_NLEXP A null value was used in an expression.

SS_NOAT Could not attach shared memory at the appropriate address: usually causedby another shared memory attach occurring before Lock Manager. Callopendb( ) first in your program to ensure correct attach address.


�

status$( )

SS_NOCMB Column Group not allowed.

SS_NOCRF No row current for column.

SS_NOCUR No row current for default value.

SS_NODB Could not get the inode of the database.

SS_NODEM Request was not a demotion request.


SS_NODF There is no default value for this column.

SS_NOENV Configuration variable not found.

SS_NOFIL File does not exist.

SS_NOLOG There is no transaction log file (for rollback).

SS_NOMEM Out of memory.

SS_NONUL Attempt to use a null in a a column where null is not allowed.

SS_NOREC No rows selected.

SS_NOREF Attempt to reference nonexistent row.

SS_NORID Invalid row ID.

SS_NORM SUCCESS.

SS_NOSHM Out of shared memory.

SS_NOTID Invalid table ID.

SS_NOTUP Row already deleted.

SS_NOVAL There is no value associated with this column.

SS_NTLCK Transaction being committed has no locks.

SS_OVRFLW Conversion overflow.

SS_PARNTMCH The number of parameters in the stored procedure declarationdoesn’t match the number of parameters in the stored proceduredefinition.

SS_PART Partial success in RDBMS operation.

SS_PROMO Lock granted, promotion occurred.

SS_RBALNE A rollback has been aborted because the transaction log is not enabled.

SS_RDACS No read permission on row or table.

SS_RDONLY A prohibited operation was attempted on a read-only database table.

SS_REF Key can’t be changed because references to it exist.

SS_RFLD Add rejected: not all required columns were entered.


status$( )

SS_RMEM No more space in database to add row.

SS_S2U An illegal ACCELL/SQL to RDBMS data type conversion.

SS_SETSMM The number of columns in the SELECT statement does not correspond tothe number of variables in the SET statement.

SS_SHMV Mismatch between the lock manager code and the shared memory datastructures (incompatible version): reload with new code and/or removeshared memory segment.

SS_SLOGFUL Syslogs is full; dump transaction log.

SS_SMDEL Partial delete, some rows were not deleted.

SS_SMUP Partial update, some rows were not updated.

SS_STFUL Selection table full.

SS_SYSER Internal system error.

SS_TXIL Invalid transaction ID.

SS_UNDACL An undefined variable was used in a SQL statement or stored procedure.

SS_UDE A developer-defined error has occurred.

SS_UDERB A developer-defined rollback error has occurred.

SS_UDFDB There was an undefined database column value in an INSERT, UPDATE, orSELECT statement.

SS_UNDBTP An attempt was made to call a stored procedure that expects aboolean value.

SS_UNSPTP An attempt was made to pass an unsupported data type (BOOL) toan ORACLE stored procedure, or an attempt was made to use avariable with an unsupported data type for an OUT parameter.

SS_UNVIEW Attempt to use an unusable view.

SS_UPDNA Update operation not allowed on form.

SS_USSER RDBMS error.

SS_VRSION Incompatible lock manager version.

SS_WRACS No write permission on row or table.


�

status$( )

In this example, status$( ) tests the success of the INSERT statement. If the insertoperation was not successful, the user is notified by a message in the fyi_messagesystem information field.

#include ”sscodes.h”...

INSERT INTO EMPLOYEEIF ( status$() <> SS_NORM ) THEN

DISPLAY ’Cannot Insert the Record’ FOR FYI_MESSAGE WAIT

CREATE PIPELINE, DEINSTALL, INSERT, INSTALL, SLOCK,UPDATE SELECTED ROWdbms_status$( ), sql_code$( ), sql_errmsg$( ), sql_state$( )

Example

See Also


str_to_char_code$( )

System function String or text conversion

��&�� )��

character (STRING/TEXT) The string or text containing the character to betranslated.

(NUMERIC)

For valid character:An integer ASCII value in the range 0 to 255.

For null character:A null NUMERIC value.

The str_to_char_code$( ) system function converts a single character string or textinto its decimal ASCII value.

This SET statement sets the digit variable to the numeric value of the character.

IF ( char >= ’0’ AND char <= ’9’ ) THENSET digit TO str_to_char_code$(char) – str_to_char_code$(’0’)

char_code_to_str$( )

Syntax

Arguments

ReturnValues

Description

Example

See Also


�

str_to_date$( )


��

value (STRING or TEXT) The string or text containing the date to betranslated.

(DATE) The DATE value of the value.

The str_to_date$( ) system function converts a string or text value to a DATE value.The date in value must be in the format determined by the DATEFMT configurationvariable. The default DATEFMT date format is MM/DD/YY.

If value is a null string or text, str_to_date$( ) returns a null DATE value.

Leading white space characters such as spaces and tabs are skipped during thetranslation.

This SET statement uses str_to_date$( ) to set the DATE variable newdate to thedate 01/01/93 when the DATEFMT configuration variable is set to the default format.

SET newdate TO str_to_date$(’1/1/93’)

date_to_mdy$( ), mdy_to_date$( ), null_convert$( ), str_to_time$( ),str_to_val$( ), to_date$( ),DATEFMT, MON1 . . . MON12

Syntax

Arguments

ReturnValues

Description

Example

See Also


str_to_time$( )


��

value (STRING or TEXT) The string or text containing the time to betranslated.

(TIME) The TIME value of the value.

The str_to_time$( ) system function converts value to a TIME value. The time in thestring must be in the form:

HH:MM

where HH is a two-digit (or one-digit for hours less than 10) hour and MM is atwo-digit number of minutes. This function assumes a twenty-four-hour clock.

If value is a null string or text value, str_to_time$( ) returns a null TIME value.

Leading white space characters, such as spaces and tabs, are skipped during thetranslation.

This SET statement uses str_to_time$( ) to set the TIME variable newtime to thetime 15:30.

SET newtime TO str_to_time$(’15:30’)

null_convert$( ), str_to_date$( ), str_to_val$( ), to_time$( )

Syntax

Arguments

ReturnValues

Description

Example

See Also


�

str_to_val$( )


��'�$ ��

value (STRING or TEXT) The string or text containing the characterrepresentation of the number to be translated.

(NUMERIC/FLOAT)

0 value cannot be converted to a numeric value or is zero-length.

FLOAT value value contains a decimal point (.).

NUMERIC valuevalue contains a valid number and no decimal point.

AMOUNT valuevalue contains a valid number and a decimal point.

The str_to_val$( ) system function converts a TEXT or STRING value to a number.This function assumes that value is a floating point number if it encounters thedecimal point (.) within value. If the string or text contains a decimal point,str_to_val$( ) returns a FLOAT value. If str_to_val$( ) does not find a decimal pointin string, it assumes that value is an integer and returns a NUMERIC value.

The only allowable characters in the input argument are:

Leading whitespace

A plus (+) or minus sign (–)

Surrounding parentheses ( )

The CURRSYM string

The TRIADSEP character

The RADIXSEP character – Digits

Syntax

Arguments

ReturnValues

Description


If value is a null string, str_to_val$( ) returns a null NUMERIC value.

Leading white space characters such as spaces and tabs are skipped during thetranslation.

If the input string contains the CURRSYM string, the function attempts to convert thestring to an AMOUNT and returns a value of type AMOUNT if successful.

If the input string contains the RADIXSEP char, the function attempts to convert thestring to a FLOAT and returns a value of type FLOAT if successful.

If the function successfully converts the string to a NUMERIC, a value of typeNUMERIC is returned.

This SET statement uses str_to_val$( ) to set the NUMERIC variable num_val tothe integer 91.

SET num_val TO str_to_val$(’ 91’)

null_convert$( ), str_to_date$( ), str_to_time$( ), to_num$( ), to_string$( ),val_to_str$( ),RADIXSEP in �� !"#�$�� '�&�� -�� *��,�.�'��

Example

See Also


�

strlen$( )


��$��

value (STRING or TEXT) The string or text that contains the characters tobe counted.

(NUMERIC) For a valid STRING or TEXT value, the number of characters isreturned. If the value is null, a null NUMERIC value is returned. ForTEXT values, the count includes special characters, such as new-lineand control characters.

The strlen$( ) system function determines the number of characters in a TEXT orSTRING value.

This example uses strlen$( ) to check whether the field variable title has more than30 characters. If title is too long, the code sample restarts the input.

FIELD ”title”ON FIELD

INPUTIF ( strlen$(title) > 30 ) THEN

BEGINDISPLAY ’Title too long—abbreviate to 30’ FOR

FYI_MESSAGE WAITRESTART ON FIELD

END

Syntax

Arguments

ReturnValues

Description

Example


strlen$( )

This example determines whether the memo variable is large. If memo containsmore than 2,000 characters, it will be opened by the vi editing program. If memo issmall, it will be edited within the form field.

FIELD ”memo”ON FIELD

IF strlen$($memo) > 2000 THENBEGINSET tmp_cmd to ’vi ’ + $memo:FILE_PATHsystem$(tmp_cmd)END

ELSEINPUT;

clip_str$( ), substr$( )See Also


�

subbinary$( )

System function Binary manipulation

��H �� ,��1��1��

binary_value(BINARY) A BINARY value that contains the binary data to beextracted.

startsub (NUMERIC) A NUMERIC integer for the starting point withinbinary_value.

endsub (NUMERIC) A NUMERIC integer for the ending point withinbinary_value.

(BINARY) A BINARY value is returned. For a null binary_value, a nullBINARY value is returned.

The subbinary$( ) system function obtains a portion of binary data from a BINARYvalue. It returns the data that starts at the startsub index within binary_value andends at the endsub index. The first character of binary_value has an index value of 1.

If startsub is out of the valid range of binary_value, substr$( ) returns a zero-lengthBINARY value. If endsub is greater than the length of binary_value, substr$( )returns all of binary_value starting at starbsub (which is shorter than the length yourequested with endsub).

This example extracts a set of integers from a list of 4-byte integers.

FOR (SET $idx TO 0; $idx < (binarylen$($intlist) / 4); SET $idx TO $idx + 1)BEGIN

SET $start TO $idx * 4;SET $end TO $start + 4:SET numeric_array[$idx] TO to_num$(subbinary$($intlist,$start,$end));

END;

binarylen$( )

Syntax

Arguments

ReturnValues

Description

Example

See Also


substr$( )

System function String or text manipulation

�� 1��1��

value (STRING or TEXT) The string that contains the substring or subtextto be extracted.

startsub (NUMERIC) The starting index within value.

endsub (NUMERIC) The ending index within value.

(STRING/TEXT)For non-null value, a STRING value is returned if value is of typeSTRING; a TEXT value is returned if value is of type TEXT. For anull value, a null value is returned.

The substr$( ) system function obtains a substring from a value. It returns thesubstring that starts at the startsub index within string and ends at the endsub index.The first character of value has an index value of 1.

If startsub is out of the valid range of value, substr$( ) returns a zero-length string. Ifendsub is greater than the length of value, substr$( ) returns all of value starting atstartsub (which is shorter than the length you requested with endsub).

Syntax

Arguments

ReturnValues

Description


�

substr$( )

In this example, substr$( ) is used to divide the emp_phone string into an area code(in area_code) and a local telephone number (in local_phone). This example sampleassumes that the telephone number in emp_phone is 14 characters long and containsthe telephone number in the form (xxx) yyy–yyyy.

SET area_code TO substr$(emp_phone, 2, 4)SET local_phone TO substr$(emp_phone, 6, 13)

This example extracts the document header from document_text.

SET $tmp_text TO substr$(document_text,1,doc_header_length)

clip_str$( ), strlen$( )

Example

See Also


system$( )


H�� &��

command_string(STRING) The string that contains the operating system command tobe executed.

(NUMERIC)

0 The operating system has successfully executed command_string.

UNDEFINED The command_string is not a valid operating system command.

system( ) valueIf the operating system cannot execute command_string, system$( )returns the value from the operating system function system( ).

The system$( ) system function executes an operating system command. Anoperating system command is a command that you would type in at the operatingsystem prompt.

This function starts a command shell and gives this shell the command_string asinput. The shell executes the commands in command_string and then exits. The typeof shell that is executed is determined by the setting of the SHELL configurationvariable.

This example uses system$( ) to call the vi editor if the user has answered “YES” inthe see_totals field.

FIELD see_totalsAFTER FIELD

IF ( see_totals = TRUE ) THENsystem$(’vi totals’)

background$( ), push_shell$( )

Syntax

Arguments

ReturnValues

Description

Example

See Also


�

to_amount$( )

System function Number conversion

��

number (NUMERIC/FLOAT/BINARY) The value to be converted.

(AMOUNT) The AMOUNT value of number.

The to_amount$( ) system function converts a number to an AMOUNT value. Thenumber can be a NUMERIC, FLOAT, or BINARY value. If number is a BINARYvalue, its length is assumed to be compatible with the length of an AMOUNT value.

The to_amount$( ) function can accept an AMOUNT argument. This functionreturns the AMOUNT value without converting it.

If number is a null value, to_amount$( ) returns a null AMOUNT value.

In this example, to_amount$() sets the AMOUNT variable amount_val to theAMOUNT value of the two fields dollars and cents. Two NUMERIC values areconverted to a single AMOUNT variable.

SET money TO (dollars * 100) + centsSET amount_val TO to_amount$(money)

to_binary$( ), to_bool$( ), to_date$( ), to_float$( ), to_num$( ), to_text$( ),to_time$( ), to_string$( ), to_string_using$( ), val_to_str$( )

Syntax

Arguments

ReturnValues

Description

Example

See Also


to_binary$( )

System function Binary conversion

��H ��

value A value of any type.

(BINARY) The binary value of value.

The to_binary$( ) system function converts a value to a BINARY value. The value tobe converted can be of any type. For a null value, a null BINARY value is returned.

The to_binary$( ) function can accept a BINARY argument. It returns the BINARYvalue without converting it.

This example creates a binary variable that contains a list of integers.

FOR (SET $idx TO 0; $idx < num_elements; SET $idx TO $idx + 1)BEGIN

SET $intlist TO $intlist + to_binary$($numeric_array[$idx]);END;

null_convert$( ), to_amount$( ), to_bool$( ), to_date$( ), to_float$( ), to_num$( ),to_string$( ), to_time$( ), to_text$( ), val_to_str$( )

Syntax

Arguments

ReturnValues

Description

Example

See Also


�

to_bool$( )

System function Boolean conversion

��$ ��

number (NUMERIC/BINARY) The value to be converted.

(BOOL)

TRUE number is nonzero (<> 0).

FALSE number is zero (0).

The to_bool$( ) system function converts a number to a BOOL value. If number is anull value, to_bool$( ) returns a null BOOL value.

If number is a BINARY value, its length is assumed to be compatible with the lengthof a NUMERIC value.

The to_bool$( ) function can accept a BOOL argument. This function returns theBOOL value without converting it.

This IF statement uses to_bool$( ) to check whether the expression “num_val +num_val2” is zero.

IF ( to_bool$(num_val + num_val2) ) THENDISPLAY ’num_val + num_val2 is nonzero’ FOR FYI_MESSAGE WAIT

null_convert$( ), to_amount$( ), to_binary$( ), to_date$( ), to_float$( ),to_num$( ), to_string$( ), to_string_using$( ), to_text$( ), to_time$( ),val_to_str$( )

Syntax

Arguments

ReturnValues

Description

Example

See Also


to_date$( )


��


(DATE) The DATE value of number.

The to_date$( ) system function converts a number to a DATE value. The numbercan be any NUMERIC or BINARY value in the range of DATE values valid in thedatabase.

If number is a BINARY value, its length is assumed to be compatible with the lengthof a DATE value.

The to_date$() function can accept a DATE argument. This function returns theDATE value without converting it.

If number is a null value, to_date$( ) returns a null DATE value.

This SET statement uses to_date$( ) to set the DATE variable date_val to the DATEvalue of 200. The DATE value of 200 is 6/04/90.

SET date_val TO to_date$(200)

date_to_mdy$( ), mdy_to_date$( ), null_convert$( ), str_to_date$( ),to_amount$( ), to_binary$( ), to_bool$( ), to_float$( ), to_num$( ), to_string$( ),to_text$( ), to_time$( ), val_to_str$( )

Syntax

Arguments

ReturnValues

Description

Example

See Also


�

to_float$( )

System function Float conversion

��$��

number (NUMERIC/AMOUNT/BINARY) The value to be converted.

(FLOAT) The FLOAT value of number.

The to_float$( ) system function converts a number to a FLOAT value. The numbercan be a NUMERIC, BINARY, or AMOUNT value.

If number is a BINARY value, its length is assumed to be compatible with the lengthof a FLOAT value.

The to_float$( ) function can accept a FLOAT argument. This function returns theFLOAT value without converting it.

If number is a null value, to_float$( ) returns a null FLOAT value.

This SET statement uses to_float$( ) to set the FLOAT variable float_val to theFLOAT value of 897. The FLOAT value of 897 is 897.00.

SET float_val TO to_float$(897)

null_convert$( ), to_amount$( ), to_binary$( ), to_bool$( ), to_date$( ),to_num$( ), to_string$( ), to_string_using$( ), to_text$( ), to_time$( ),val_to_str$( )

Syntax

Arguments

ReturnValues

Description

Example

See Also


to_num$( )

System function Number conversion

��

value (AMOUNT/BINARY/BOOL/DATE/FLOAT/TIME ) The value to beconverted.

(NUMERIC) The NUMERIC value of value.

The to_num$( ) system function converts a value to a NUMERIC value. This valuecan be of any type except STRING or TEXT. If the argument is a FLOAT orAMOUNT, it must be in the range between –231 and +231–1; otherwise, it istruncated. If the argument is a BOOL, FALSE returns 0 and TRUE returns 1. If theargument is DATE or TIME, any value is legal and the inverse of the to_date$( ) orto_time$( ) functions will be performed.

If value is a BINARY value, its length is assumed to be compatible with the length ofa numeric value.

The to_num$( ) function can accept a NUMERIC argument. This function returns theNUMERIC value without converting it.

If value is a null value of type AMOUNT, BOOL, DATE, FLOAT or TIME,to_num$( ) returns a null NUMERIC value.

This SET statement uses to_num$( ) to set the NUMERIC variable num_val to theNUMERIC value of 8997.34. The NUMERIC value of 8997.34 is 8997.

SET num_val TO to_num$(8997.34)

null_convert$( ), str_to_val$( ), to_amount$( ), to_binary$( ), to_bool$( ),to_date$( ), to_float$( ), to_string$( ), to_text$( ), to_time$( ), val_to_str$( )

Syntax

Arguments

ReturnValues

Description

Example

See Also


�

to_string$( )


��

value (AMOUNT/BINARY/BOOL/DATE/FLOAT/NUMERIC/TEXT/TIME) The value to be converted.

(STRING) The string value of value.

The to_string$( ) function converts value to a string. This value can have any of thefollowing ACCELL/SQL data types: NUMERIC, FLOAT, BOOL, AMOUNT, DATE,TEXT, BINARY, or TIME.

The to_string$( ) function converts value from one internal data type format toanother. The val_to_str$( ) function converts value from one external (display) datatype format to another.

Number values (NUMERIC, FLOAT, and AMOUNT) are converted to a stringcontaining the number. Amount values include the radix separator but not thecurrency symbol. Float values are not rounded. BOOL values are converted to thestrings “YES” or “NO”. DATE and TIME values are converted to their stringequivalents.

Text values are truncated at the first newline or other control character.

Binary values are truncated at the first newline or other control character or at thefirst unprintable character.

The to_string$( ) function can accept a STRING argument. This function returns theSTRING value without converting it.

Syntax

Arguments

ReturnValues

Description


to_string$( )

If value contains a null value of any data type, to_string$( ) returns a null string. Toreturn a string containing the null format for the data type associated with value, usethe ACCELL/SQL system function val_to_str$( ).

The default null display character for strings is *. You can change the STRING nullcharacter by setting either of the ACCELL/SQL configuration variables STRNULLCHor NULLCH.

The first SET statement uses to_string$( ) to assign the string “91” to char_val.

SET char_val TO to_string$(91)

The next SET statement uses to_string$( ) to assign to date_str the string equivalentof the DATE value in in_date. If in_date has a DATE value of 7/12/87, date_strcontains the string 07/12/87. If in_date contains a null value, date_str contains thenull string ***********.

SET date_str TO to_string$(in_date)

This last example statement uses to_string$( ) to convert the NULL constant into anull STRING value. This null value is then passed as an argument to the user-definedACCELL/4GL function user_func( ).

SET result TO user_func( to_string$(NULL) )

The NULL constant has no data type associated with it. To use this constant as anargument (or in any context where data type is required), the constant must beconverted to a null value that has a data type. You can use any of the data typeconversion functions (such as to_amount$( ), to_bool$( ), to_date$( ), to_float$( ),to_time$( ) ) in the same way.

str_to_val$( ), to_amount$( ), to_binary$( ), to_bool$( ), to_date$( ), to_float$( ),to_num$( ), to_text$( ), to_string_using$( ), val_to_str$( )

Example

See Also


�

to_string_using$( )


�� '�� &��

value (AMOUNT/FLOAT/NUMERIC/STRING/TEXT) The value to be formatted.

format_string (STRING) The string that contains the formatting information.

(STRING) The value formatted according to format_string.

The to_string_using$( ) system function formats a value according to theformat_string. This value can actually have any of the ACCELL/SQL data types.However, you can specify a format string only for the data types TEXT, STRING,NUMERIC, FLOAT, or AMOUNT. If value is a null value, to_string_using$( )returns a string filled with the appropriate null character. The default null displaycharacter for strings is *.

The null string returned has the length of format_string regardless of the formatactually in this string.

The format_string can include any of the display formats valid in the USING clauseof the DISPLAY statement. The USING clause determines how AMOUNT,NUMERIC, FLOAT, and STRING values appear in the field window. Ifformat_string is a null string or is a zero-length string, to_string_using$( ) uses adefault string format. This format is the same format used by the DISPLAY statementwhen the USING clause is omitted.

This function is useful if you need to send formatted data over a pipeline. You cancapture the results of a DISPLAY USING statement with to_string_using$( ).

Syntax

Arguments

ReturnValues

Description


to_string_using$( )

This SET statement uses to_string_using$( ) to set the STRING variableamount_str to the formatted value of the AMOUNT variable amount_val. Ifamount_val contains the value 1246.75, amount_str contains the string $1,246.75.

SET amount_str TO to_string_using$(amount_val, ’$$,$$$.&&’)

to_amount$( ), to_bool$( ), to_float$( ), to_string$( ), val_to_str$( )DISPLAY

Example

See Also


�

to_text$( )

System function TEXT conversion

��

value A value of any type.

(TEXT) The text value of value.

The to_text$( ) system function converts a value of any type to a TEXT value. Ifvalue is null, the value returned is null.

Number values (NUMERIC, FLOAT, and AMOUNT) are converted to a stringcontaining the number. Amount values include the radix separator but not thecurrency symbol. Float values are not rounded. BOOL values are converted to thestrings “YES” or “NO”. DATE and TIME values are converted to their stringequivalents.

The to_text$( ) function can accept a TEXT argument. It returns the TEXT valuewithout converting it.

Binary values are truncated at the first newline or other control character or at thefirst unprintable character.

This example creates a text variable that contains a list of employee names and hiredates.

SET $first_name, $last_name, $hire_date TOSELECT first_name, last_name, hire_date FROM employeeWHERE hire_date < $year_end

EXECUTINGSET $tmp_text TO $tmp_text + $first_name + ’ ’ + $last_name + ’ ’;SET $tmp_text TO $tmp_text + to_text$($hire_date);SET $tmp_text TO $tmp_text + char_code_to_str$(013);

END;

null_convert$( ), to_amount$( ), to_binary$( ), to_bool$( ), to_date$( ),to_float$( ), to_num$( ), to_string$( )

Syntax

Arguments

ReturnValues

Description

Example

See Also


to_time$( )

System function TIME conversion

��


(TIME) The TIME value of number.

The to_time$( ) system function converts a number to a TIME value. The numbercan be any integer and is interpreted as the number of minutes since midnight.

If number is a binary value, its length is assumed to be compatible with the length ofa TIME value.

The to_time$( ) function can accept a TIME argument. This function returns theTIME value without converting it.

If number is a null value, to_time$( ) returns a null TIME value.

This SET statement uses to_time$( ) to set the TIME variable time_val to the TIMEvalue of 572. The TIME value of 572 is 9:32.

SET time_val TO to_time$(572)

null_convert$( ), str_to_time$( ), to_amount$( ), to_binary$( ), to_bool$( ),to_date$( ), to_float$( ), to_num$( )

Syntax

Arguments

ReturnValues

Description

Example

See Also


�

to_value$( )

System function ACCELL/SQL object conversion

��'�$� ��

value Any ACCELL/SQL constant, variable, or expression.

An ACCELL/SQL object.

The to_value$( ) system function allows macro arguments to be passed asACCELL/SQL objects to an SQL statement.

When the select1 macro is expanded by the preprocessor, the to_value$( ) systemfunction is recognized as an ACCELL/SQL object. The value of arg1 is thereforeprepared as an ACCELL/SQL object within a SQL statement.

#define select1(arg1) \SELECT emp_last_name FROM employee WHERE emp_last_name = to_value$(arg1)

“SQL Statements” in the “Using Script Statements” chapter of �� !"#�$2�� &�3��"��

Syntax

Arguments

ReturnValues

Description

Example

See Also


tx_mode$( )

System function : Status checking RDBMS dependent

��

INFORMIX Supported.

INGRES The tx_mode$( ) system function has no effect because INGRESalways automatically starts a multistep transaction when the firstSQL statement is executed after a CONNECT, COMMIT, orROLLBACK statement.

ORACLE The tx_mode$( ) system function has no effect because ORACLEalways automatically starts a multistep transaction when the databaseis opened or after a transaction is committed or rolled back.

SYBASE SQLServer

Supported.

Unify DataServerThe tx_mode$( ) system function has no effect because UnifyDataServer always automatically starts a multistep transaction at theappropriate time.

mode One of the values TRUE, FALSE, or UNDEFINED.

(BOOL)

TRUE Automatic transaction handling is enabled.

FALSE Automatic transaction handling is disabled.

The tx_mode$( ) system function specifies whether automatic transaction handling isenabled or disabled.

By default, the ACLTXMODE configuration variable is set to TRUE and ACCELL/SQLautomatically begins and commits transactions. However, if the ACLTXMODEconfiguration variable is set to FALSE, automatic transaction handling is disabled.

Syntax

Support

Arguments

ReturnValues

Description


�

tx_mode$( )

When automatic transaction handling is disabled, transaction levelspecifications have no effect, and shared locks are released after a commit or rollbackoperation.

You can use tx_mode$( ) to dynamically enable or disable automatic transactionhandling, regardless of the setting of ACLTXMODE.

To determine (but not change) the current transaction mode, specify the UNDEFINEDargument for tx_mode$( ).

WarningWhen you call tx_mode$(FALSE) to turn off automatic transaction handling,always follow the call with a COMMIT WORK statement to prevent loss of work.Using tx_mode$( ) to turn off transaction handling does not commit the currenttransaction.

In this example, automatic transaction handling is first disabled, and then the currenttransaction, if any, is committed. A new transaction is then started to process andcommit an update operation.

tx_mode$(FALSE)COMMIT WORKBEGIN WORK

UPDATE emp SET vac = vac + 8;COMMIT WORK

BEGIN WORK, CHOOSE FIRST FORM, CHOOSE NEXT FORM, COMMITWORK, ROLLBACK WORKACLTXMODE in �� !"#�$�� '�&�� -�� *��,�.�'��

Example

See Also


ui_type$( )


��H��

variable (STRING) A variable that returns the current presentation mode.

CHARACTER Character user interface

OPENLOOK .>��*..@ graphical user interface

MOTIF #�� graphical user interface

MSWINDOWS Windows graphical user interface

(BOOL)

TRUE The ui_type$( ) function was completed successfully.

FALSE The ui_type$( ) function was not completed successfully.

The ui_type$( ) system function enables you to return at runtime information aboutthe user interface being used. You can use the ui_type$( ) function to executeconditional script segments that are specific to a user interface.

This function fails only when an internal error occurs.

Syntax

Arguments

ReturnValues

Description


�

ui_type$( )

The following script example displays a picture of the company logo on the screen ifthe user is using the .>��*..@ user interface option. Otherwise, the companyname is displayed on the screen instead.

IF ui_type$($pres_mode)=FALSE THENBEGIN/* internal error, should never occur */DISPLAY ’internal error in ui_type$()’ FOR FYI_MESSAGE WAITEND

ELSE IF $pres_mode=’OPENLOOK’ THENBEGIN/*display company logo via C-hook */display_logo($company_name)END

ELSEBEGIN/* display company name in system information field */DISPLAY $company_name FOR FYI_MESSAGE WAITEND

db_type$( ), os_type$( )�� !"#�$��,�(��

Example

See Also


update_allowed$


��$$�G��

(BOOL)

TRUE The user has permission to perform interactive update operations onany standard form.

FALSE The user does not have permission to perform interactive updateoperations on any standard form.

The update_allowed$ system variable controls the user’s application accessprivilege for interactive update operations. The application access privileges controlwhat interactive database operations the user has access to on all application forms.These privileges are application-wide: they apply to all interactive operations on allstandard forms.


If both the update_allowed$ application access privilege and theUPDATE_ALLOWED form access privilege are set to TRUE, the user is allowed toperform interactive update operations. If either the update_allowed$ applicationaccess privilege or the UPDATE_ALLOWED form access privilege is set to FALSE,the user cannot perform interactive update operations. The UPDATE_ALLOWEDform access privilege is a form attribute and can be set from the ACCELL/GeneratorForm Definition form or from within the form script.

The default null display character is *. You can change the null display characters, bysetting the ACCELL/SQL configuration variables NULLCH, AMTNULLCH,BOLNULLCH, DATNULLCH, FLTNULLCH, STRNULLCH, TIMNULLCH, andTXTNULLCH.

Syntax

LegalValues

Description


�

update_allowed$

In this example, the group_id$() system function is used to determine the user’sgroup ID. The update operation permission is set to TRUE if the user belongs to agroup with a group ID equal to 10.

IF (group_id$() = 10) THENSET update_allowed$ to TRUE

add_allowed$, delete_allowed$, find_allowed$UPDATE_ALLOWED in the “Attributes Summary” chapter of this manual�� !"#�$��,�(�� !"#�$�0� �&� &��

Example

See Also


user_id$( )


��

(NUMERIC) The operating system user ID number of the user.

The user_id$( ) system function obtains the user’s ID number from the operatingsystem. This function is useful for recording the identity of the user who makescertain modifications to the database.

In this example, user_id$( ) sets the emp_uid variable to the user ID of the user whois currently executing the application.

BEFORE ADDSET emp_uid TO user_id$()

get_default_schema$( ), get_password$( ), group_id$( ), group_name$( ),user_name$( )

Syntax

ReturnValues

Description

Example

See Also


�

user_name$( )


��

(STRING) The operating system login name of the user.

The user_name$( ) system function obtains the user’s login name from the operatingsystem. This function is useful for recording the identity of the user who makescertain modifications to the database.

In this example, user_name$( ) sets the emp_name variable to the login name of theuser who is currently executing the application.

BEFORE ADDSET emp_name TO user_name$()

get_default_schema$( ), get_password$( ), group_id$( ), group_name$( ),user_id$( )

Syntax

ReturnValues

Description

Example

See Also


val_to_str$( )


'�$��

value (AMOUNT/BINARY/BOOL/DATE/FLOAT/NUMERIC/TEXT/TIME) The value to be converted.

(STRING) The string value of value.

The val_to_str$( ) system function converts value to a string. Number values(NUMERIC, FLOAT, and AMOUNT) are converted to a string containing thenumber. Amount values include the decimal point but not the dollar sign. Floatvalues are not rounded. Boolean values are converted to the strings “YES” or “NO”.Date and time values are converted to their string equivalent.

Text values are truncated at the first newline or other control character.

Binary values are truncated at the first control character or at the first unprintablecharacter.

No leading or trailing spaces are included in the returned string.

If value contains a null value, val_to_str$( ) returns a string containing the null valuefor the data type associated with value. To return a null string when value is null, usethe ACCELL/SQL system function to_string$( ).

The to_string$( ) function converts value from one internal data type format toanother. The val_to_str$( ) function converts value from one external (display) datatype format to another.

Syntax

Arguments

ReturnValues

Description


�

val_to_str$( )

This SET statement uses val_to_str$( ) to assign the string “91” to char_val.

SET char_val TO val_to_str$(91)

This SET statement uses val_to_str$( ) to assign to date_str the string equivalent ofthe DATE value in in_date. If in_date had a DATE value of 7/12/87, date_str wouldcontain the string 07/12/87. If in_date contained a null value, date_str wouldcontain the null string for DATE: **********.

SET date_str TO val_to_str$(in_date)

null_convert$( ), str_to_val$( ), to_amount$( ), to_binary, to_bool, to_date$( ),to_float, to_num$( ), to_string$( ), to_string_using$( )NULLCH, AMTNULLCH, BOLNULLCH, DATNULLCH, FLTNULLCH, STRNULLCH,TIMNULLCH, and TXTNULLCH in �� !"#�$�� '�&�� -�� *��,.�'��

Example

See Also


yesno$( )

System function Screen I/O

H�� ,�� &��'��

yes_no_msg (STRING) A string containing the question to be displayed in thefyi_message system information field.

default_value (NUMERIC) An integer value to control the default response to thequestion’s possible values:

1 Default response is “yes”.

0 Default response is “no”.

–1 No default; user response is required.

–2 A response of “yes” is auto-accepted.

–3 A response of “no” is auto-accepted.

–4 No response is required.

(BOOL)

TRUE The user’s response to the yes_no_msg prompt is either “yes” or“YES”.

FALSE The user’s response to the yes_no_msg prompt is either “no” or“NO”.

The yesno$( ) system function displays a prompt message, yes_no_msg, in thefyi_message system information field and then waits for the user’s response.

If default_value is set to –1, the user must answer the yes_no_msg with one of theresponses “yes” or “no”. The default_value controls the default action for theresponse.

Syntax

Arguments

ReturnValues

Description


�

yesno$( )

If default_value is set to 1, the yes_no_msg receives the answer “YES” if the userpresses �� without entering a response. If default_value is set to 0, theyes_no_msg receives the answer “NO” if the user does not enter a response.Auto-accepted responses do not require the user to press ��.

You can change the valid responses of “yes” and “no” by modifying the$UNIFY/unify.msg file and rebuilding the unify.msg file.

This example uses yesno$( ) to ask the user whether to continue to the next record ifthe current record is not stored in the database.

ON NEXT RECORDIF ( NOT (is_current_record_stored$() ) THEN

BEGINIF ( yesno$(’You are about to loose your record changes? Save them?’, –1) THEN

BEGINDISPLAY ’Updating...’ for FYI_MESSAGEUPDATE CURRENT RECORDDISPLAY ’Record Updated’ FOR FYI_MESSAGE

ENDEND

If the current record is not stored and the user answers “yes” to the prompt:

You are about to loose your record changes? Save them?

The current record is stored with the UPDATE CURRENT RECORD statement.

�� !"#�$��4� &�� ,“Customizing Messages anf Forms” in �� !"#�$��4� &�� ,bldcmf in �� !"#�$�� '�&�� -�� *��,�.�'��

Example

See Also

��

Predefined CFunctions

��

��

486 Predefined C Functions

�

� ��

This chapter contains complete descriptions of predefined C functions.These functions can be called by C-hooks which are global functionswritten in the C language. A discussion of C-hooks and theirimplementation is found in �� .

Descriptions of the predefined C functions appear in alphabetical orderand include several parts:

The name of the C function is enclosed by an ovaloutline at the top of the page. This indicates thebeginning of a syntax description.


Category The category, or type, of C function is shown beneath thesection name, as well as dependencies, if any.

Syntax Presents the syntax for the function. BOLDFACE wordsare keywords. Italicized words within the syntax aredescribed under Arguments.


Arguments Describes the italicized arguments shown in the syntax.

Return Values Describes the values returned by the function.

Status Values Describes the values that the variable can return.

Description Describes usage, conditions, and notes.

Example Gives a sample that shows how the function might beused.

See Also Lists other statements, sections, attributes, or manualsthat are related to the function.

487Predefined C Functions

uaclbw( )

Predefined C function Graphical user interfaces only

��

��

��

�� !�� !��"

#$%&%#$ !�� !�"

widget_ID Pointer to the returned ACCELL/SQL current base window widget ID

status Pointer to the returned function status value

The uaclbw( ) function is called by a C-hook to retrieve the ACCELL/SQLapplication’s current base window widget ID. This is useful when implementingspecial features of a graphical user interface (GUI) such as adding other windows to aparent window. The figure illustrates the current base window. For more information,refer to the documentation for the particular GUI product you are using.

��

��

��

All #include statements shown in the Syntax section are required in the caller’ssource file. See Appendix B of this manual for a description of the required .h files.

TRUE The operation was successful.

FALSE A failure occurred during the operation. Check the status value forthe error.

Syntax

Arguments

Description

ReturnValues


�

uaclbw( )

UENORM The operation was successful. The widget_ID is valid.

UEINVAL The operation failed due to an incorrect ACLPRESMODE setting. Thewidget_ID is 0.

UENOWRK The operation failed because there is no current base window widgetID to return. The widget_ID is 0.

�� "�#�� #�� $�� %� �&�� # '�� $ ��

StatusValues

See Also


uaclcfld( )


��

��

��

�� !�� !��#$%&%#$ !�� !�"

widget_ID Pointer to the returned ACCELL/SQL current field widget ID.

status Pointer to the returned function status value.

The uaclcfld( ) function is called by a C-hook to retrieve the current field widget IDfor the ACCELL/SQL application. The current field widget is the current target fieldwidget. This is useful when implementing special features of a graphical userinterface (GUI) such as customizing the field color. For more information, refer to thedocumentation for the particular GUI product you are using.




Syntax

Arguments

Description

ReturnValues


�

uaclcfld( )

UENORM The operation was successful. The widget_ID is a valid widget ID.


UENOWRK The operation failed because there is no current field widget ID toreturn. The widget_ID is 0.

�� "�#�� #�� $�� %� �&�� # '�� $ ��

StatusValues

See Also


uacldbid( )

Predefined C function RDBMS dependent

��

��

��

��(�� !��#'()'�!�(��"#$%&%#$�!�� !�"

INFORMIX Not supported: For INFORMIX, the uacldbid( ) function returnsTRUE with *dbidp set to 1.

INGRES Not supported: For INGRES, the uacldbid( ) function returns TRUEwith *dbidp set to 1.

ORACLE Not supported: For ORACLE, the uacldbid( ) function returns TRUEwith *dbidp set to 1.

SYBASESQL Server

Not supported: For SYBASE SQL Server, the uacldbid( )function returns TRUE with *dbidp set to 1.


dbidp Pointer to the returned database ID.

status Pointer to the returned RHLI function system value.

The uacldbid( ) function sets the passed parameter dbidp pointer to the location ofthe database identifier for the database opened by ACCELL/SQL.


WarningNever attempt to close the database that has been opened by ACCELL/SQL.ACCELL/SQL automatically closes the database when the application exits.

Syntax

Support

Arguments

Description


�

uacldbid( )

USUCCESS The operation was successful.

UFAILURE A failure occurred during the operation. Check the status value forthe error.

UENORM Operation was successful. The dbidp parameter points to thedatabase location.

UEDBCLS The database is closed.

The following example prints a message if the current database ID could not beretrieved.

UDBID dbid;

if (! uacldbid(&dbid, &status)){

fprintf(stderr, ”Unable to get ACCELL/SQL database ID: status = %ld\n”, status);

}else{

/* Get current process ID */if (! uallpid(dbid, &npid, &pidl, &status)){

fprintf(stderr, ”Unable to get all process ID info: status = %ld\n”, status);

}if (npid > 0){

free ((char *) pidl);}

uaclrid( ), uacltx( )�� )�*+ ��

ReturnValues

StatusValues

Example

See Also


uacldbp( )

Predefined C function SYBASE SQL Server only

��

��

��

��*��

��*��

��(�� !��'(+,-�.$$�!!�(��"#$%&%#$�!�� !�"

INFORMIX The uacldbp( ) function is not supported for INFORMIX.

INGRES The uacldbp( ) function is not supported for INGRES.

ORACLE The uacldbp( ) function is not supported for ORACLE.

SYBASE SQLServer

Supported.

Unify DataServer The uacldbp( ) function is not supported for Unify DataServer.

WarningIf the RDBMS does not support the function, trying to load a custom managercauses amgr.ld to fail and the function to be undefined.

dbprocess Address of a pointer to the SYBASE SQL Server DBPROCESSstructure.




Syntax

Support

Arguments

ReturnValues


�

uacldbp( )


UECMFATL Internal error (nonfatal).

The uacldbp( ) C function sets the passed DBPROCESS pointer to the address of theSYBASE SQL Server database to be used by ACCELL/Manager. The DBPROCESSstructure is required to perform any database operation through the SYBASEDB-Library SQL Interface. C-hooks can use the SYBASE DB-Library SQL Interfacefunctions with the pointer to the DBPROCESS structure obtained by calling thisfunction.

Call the uacldbp( ) function every time you call a C-hook to perform a SYBASE SQLServer DB-Library call. If an ACCELL/SYBASE scan is active, uacldbp( ) saves theactive scan in the nested query manager’s area.

The sybfront.h and sybdb.h include files are used to call SYBASE SQL Serverroutines or declare SYBASE SQL Server variables. Attempting to call uacldbp( ) foran unsupported RDBMS results in a linking error.


The following example shows how the uacldbp( ) function can be used to acquire apointer to the DBPROCESS structure and perform database operations.

DBPROCESS *dbprocess;USTATUS status;

/* get dbprocess */if(!uacldbp(&dbprocess, &status))

{fprintf(stderr, ”Unable to get a pointer to DBPROCESS”);return(0);}

uaclwhr( )�� )�*+ ��

StatusValues

Description

Example

See Also


uaclform( )


��

��

��

��/�� !�� !��#$%&%#$ !�� !�"

widget_ID Pointer to the returned ACCELL/SQL current form widget ID.


The uaclform( ) function retrieves the current form widget ID for the ACCELL/SQLapplication.

The uaclform( ) function is called by a C-hook to retrieve the ACCELL/SQLapplication’s current form widget ID. This is useful when implementing specialfeatures of a graphical user interface (GUI) such customizing the current window.The figure illustrates the current form. For more information, refer to thedocumentation for the particular GUI product you are using.

��

��

��


Syntax

Arguments

Description

Description


�

uaclform( )





UENOWRK The operation failed because there is no current form widget ID toreturn. The widget_ID is 0.

�� "�#�� #�� $�� %� �&�� # '�� $ ��

ReturnValues

StatusValues

See Also


uacllda( )

Predefined C function ORACLE RDBMS only

��

��

��

��#� �� !�� !!#� "#$%&%#$�!�� !�"

INFORMIX The uacllda( ) C function is not supported for INFORMIX.

INGRES The uacllda( ) C function is not supported for INGRES.

ORACLE Supported.

SYBASE SQLServer

The uacllda( ) C function is not supported for SYBASESQL Server.

Unify DataServer The uacllda( ) C function is not supported for Unify DataServer.

WarningIf the RDBMS does not support the function, trying to load a custom managercauses amgr.ld to fail and the function to be undefined.

lda Pointer to the returned address of the ORACLE LDA structure.


The uacllda( ) function sets the pointer to the LDA (ORACLE logon data area)structure for the ORACLE database used by ACCELL/Manager. The LDA structure isrequired to perform any database operation through the ORACLE Call Interface (OCI).C-hooks can use the OCI functions with the pointer to the LDA structure obtained bycalling this function. Attempting to call uacllda( ) for an unsupported RDBMS resultsin a linking error.

For more information about using the ORACLE LDA structure, see your ORACLE CallInterface Programmer’s Guide.

Syntax

Support

Arguments

Description


�

uacllda( )





UEINVAL Invalid value; value is not valid on the current database.

UEFAULT Invalid parameter passed.

UENOEM Operation successful.

The following sample code shows how the uacllda( ) function can be used to acquirea pointer to the LDA (ORACLE logon data area) structure and perform databaseoperations. This example finds all tables owned by the current user.

LDA *lda;CDA crs1, crs2;USTATUS status;/* get lda */if(!uacllda(&lda, &status)){

fprintf(stderr, ”Unable to get a pointer to LDA );return(0);

}

/* open cursor */if (oopen(&crs1, lda, (char *)0, –1, –1, (char *)0, –1)){

return(0);}

ReturnValues

StatusValues

Example


uacllda( )

/* parse query */if (osql3(&crs1, ”select TNAME from TAB where TABTYPE=’TABLE’”, –1)){

return(0);}

/* execute query */if (oexec(&crs1)){

return(0);}

�� )�*+ �� See Also


�

uaclrid( )

Predefined C function Unify DataServer only

��

��

��

#,)'�� !��#$%&%#$�!�� !� "

INFORMIX Not supported: For INFORMIX, the uaclrid( ) C function returnsFALSE with *status set to 0.

INGRES Not supported: For INGRES, the uaclrid( ) C function returnsFALSE with *status set to 0.

ORACLE Not supported: For ORACLE, the uaclrid( ) C function returnsFALSE with *status set to 0.

SYBASE SQLServer

Not supported: For SYBASE SQL Server, the uaclrid( )C function returns FALSE with *status set to 0.


status Pointer to the returned RHLI function system status value.

The uaclrid( ) function retrieves the identifier of the row in the selected set that iscurrently being processed by AMGR. The row identifier is useful for retrieving textand binary information.

The uaclrid( ) function is valid only on a form with a target table. This functionshould not be called by a C-hook that is called from a global function. Use uaclrid( )only in add-update mode, not in find mode. If uaclrid( ) is called when there is noselected set, the function fails and the status value is set to UENOROW.

Syntax

Support

Arguments

Description


uaclrid( )


WarningModifying columns of the row does not cause the AMGR display to be updated. It istherefore recommended that displayable fields not be modified.

Row ID The operation was successful.

ANULLRID An attempt was made to access an unsupported DBMS or an erroroccurred

UENOROW The row ID cannot be retrieved.

UENOIMP An attempt was made to access an unsupported DBMS.

The following sample code shows how the uaclrid( ) function can be used to obtainthe row ID.

URID curr_rid;USTATUS status;

chk_rowid(nargs, acclarg) int nargs; AVAL acclarg[];{

...

if (! uaclrid(&curr_rid, &status)) { fprintf(stderr, ”Unable to get ACCELL/SQL row ID: status = %ld\n”, status); }

else { /* * Print row id to log file to identify which row was current * when chk_rowid() was called. */ fprintf(log_fp, ”chk_rowid(): Row id = %d\n”, curr_rid); }

...

}

ReturnValues

StatusValues

Example


�

uaclrid( )

uacldb( ), uacltx( ), uaclwhr( )',��- .///� �� )0�� #�� ACCELL/SQL: RDBMS Integration

See Also


uacltwid( )


��

��

��

��1 �� !�� !��"

#$%&%#$�!�� !�"

widget_ID Pointer to the returned top-level widget ID. The widget_ID should becast to the type Widget by the calling routine.


The uacltwid( ) function returns the top-level widget ID for the ACCELL/SQLapplication. If the application is running in character mode, the uacltwid( ) functionfails, returning FALSE with a status of UEINVAL. If the application is running in agraphical user interface mode, uacltwid( ) returns TRUE with widget_ID set to thetop-level widget ID.

All #include statements shown in the Syntax section are required in the caller’ssource file. See Appendix B for a description of the required .h files.


FALSE A failure occurred during the operation; check status value for theerror.


UEINVAL The operation failed due to an incorrect ACLPRESMODE setting. Thewidget_ID is zero (0).

�� "�#�� #�� $�� %� �&�� # '�� $ ��

Syntax

Arguments

Description

ReturnValues

StatusValues

See Also


�

uacltx( )

Predefined C function RDBMS dependent

��

��

��

��0�2�� !��#%1)'�!�2��"#$%&%#$�!�� !�"

INFORMIX Not supported: For INFORMIX, the uacltx( ) C function alwaysReturns TRUE with *txidp set to 1.

INGRES Not supported: For INGRES, the uacltx( ) C function always ReturnsTRUE with *txidp set to 1.

ORACLE Not supported: For ORACLE, the uacltx( ) C function alwaysReturns TRUE with *txidp set to 1.

SYBASESQL Server

Not supported: For SYBASE SQL Server, the uacltx( ) Cfunction always Returns TRUE with *txidp set to 1.


txidp Pointer to the returned ACCELL/SQL current transaction ID.

status Pointer to the returned RHLI function system value.

The uacltx( ) function stores the current transaction ID to the location specified bytxidp. It is useful in C-hooks that call RHLI functions.


WarningNever try to roll back or commit the current ACCELL/SQL transaction throughthe RHLI. Use the ROLLBACK WORK statement to roll back an ACCELL/SQLtransaction. To commit a transaction, either use the COMMIT WORK statement orstart execution of a form at the Start Tx or Restart Tx transaction level.

Syntax

Support

Arguments

Description


uacltx( )



UEILTX The transaction ID is invalid.


When used with UNIFY DataServer, any of the status values returned by sqlcbtx( )are possible. Refer to the UNIFY DataServer documentation.

The following example prints a message if unable to retrieve the current transactionID.

UTXID txid;USTATUS stat;USTATUS statl[1];UUSRINF usrinf;UOID uid;

if (! uacltx(&txid, &stat)){

fprintf(stderr, ”Unable to get ACCELL/SQL transaction ID: status = %ld\n”, stat);

}else{

/* Get info about current user */uid = getuid();if (! uinfusr(txid, 1, &uid, UCLASS2, &usrinf, statl, &stat)){

fprintf(stderr, ”Unable to get current user info: status = %ld\n”, stat);

}}

uacldbid( ), uaclrid( )�� )�*+ �� ',��- .///� �� )�$��

ReturnValues

StatusValues

Example

See Also


�

uaclwhr( )

Predefined C function

��

��

��

� ��!�� !��#$%&%#$�!�� !�


No privileges are needed to execute this function. However, permissions are requiredto perform database operations.

If successful, returns a pointer to the WHERE clause, not includingthe keyword WHERE. This pointer remains in effect only until thenext call to uaclwhr( ).

(char *)0 Operation was not successful.

UENOROW The row ID cannot be retrieved, for example, because there is nocurrent row, because the form is in find mode, or because the formhas no target table.

UENORM The operation was successful.

UENOMEM Insufficient memory is available.

The uaclwhr( ) function is called only from a C-hook. In add-update mode, theuaclwhr( ) function returns a pointer to a string that contains a WHERE clause. TheWHERE clause can then be concatenated with other clauses to build a command toupdate, delete, or select the current record on the current form. This function istypically used to select text or binary columns associated with the current record.

Syntax

Arguments

Security

ReturnValues

StatusValues

Description


uaclwhr( )

uaclwhr( ) is valid only on a form with a target table. This function should not becalled by a C-hook that is called from a global function. Use uaclwhr( ) only inadd-update mode, not in find mode. If uaclwhr( ) is called when there is no selectedset, the function fails and the status value is set to UENOROW.


TipYou can use the WHERE clause that is returned by the uaclwhr( )predefined C function to find the current record in the selected set.

This example shows a portion of a C program that builds and executes a query thatselects the pic_data column for the current record.

charsqltext[2048];{strcpy(sqltext, ”SELECT pic_data FROM pic_tab WHERE ”);strcat(sqltext, uaclwhr(picstatus));exec_sql(sqltext); /* function executes a SQL statement */}

uacldbp( ), uacllda( ), uacldb( )

Example

See Also


�

uaclwnd( )


��

��

��

�� !�� !��"#$%&%#$ !�� !�"

widget_ID Pointer to the returned ACCELL/SQL current master applicationbase-window widget ID.


The uaclwnd( ) function is called by a C-hook to retrieve the ACCELL/SQL masterapplication’s base-window widget ID. This is useful when implementing specialfeatures of a graphical user interface (GUI). The figure illustrates the masterapplication base window. For more information, refer to the documentation for theparticular GUI product you are using.

��

��

��




Syntax

Arguments

Description

StatusValues


uaclwnd( )



UENOWRK The operation failed because there is no current base window widgetID to return. The widget_ID is 0.

�� "�#�� #�� $�� %� �&�� # '�� $ ��,ACLPRESMODE in �� $��!� �� 3 �� (#� �� '��#��4 )�$��

StatusValues

See Also


�

511

Appendixes

512

�

��

Appendix A: ACCELL/SQL ReservedWords

The following words are reserved for use by ACCELL/SQL and must notbe used as identifiers in forms or scripts. However, keywords can be usedin quoted identifiers.

ACCELL_TYPEACTIONADDADD_ALLOWEDADD_UPDATEAUD_ACTIONAUD_LABELAUD_ON_ENTRYAFTERALLALTERAMOUNTANDAPPLICATIONARCHIVESAREASCENDINGATAUD_ACTION

AUD_LABELAUD_ON_ENTRYAUTO_ACCEPTAUTO_COMMITAUTO_EDITAUTO_FINDAUTO_ZOOM

BEFOREBEGINBEGIN_SQLBINARYBLINKBOOLBOUNDEDBREAKBREAKPOINTBUTTONBY

514 Appendix A: ACCELL/SQL Reserved Words

CACHEDCANCEL_ZOOMCASECASE_CONVERSIONCENTEREDCHANGECHANGESCHOOSECLEARCLEAR_ADD_EXPCLEAR_AFTER_AUCLEAR_FIND_EXPCLICK_ON_FIELDCLOSECODE_SECTIONCOLCOL_ORIGINCOLUMN_INDEXCOLUMN_LOWER_BOUNDSCOLUMN_UPPER_BOUNDSCOLUMNSCOMMANDCOMMITCONTINUECREATECUR_FIELDCUR_NEXT_FIELDCURRENT

DATA_TYPEDATEDB_LENGTH

DB_TYPEDBMS_ERRORDEFAULTDEFINEDEINSTALLDELETEDELETE_ALLOWEDDESCENDINGDIMENSIONDISABLEDISABLEDDISPLAYDISPLAY_FORMATDISPLAY_JUSTIFYDROP

��

��

��

��

��

��

��

��

��

��

��

��

��

��

515Appendix A: ACCELL/SQL Reserved Words

��

��

��

��

��

��

��

��

��

��

��

��

��

��

��

��

��

��

��

��

��

��

��

��

��

��

��

��

��

��

��

��

��

��

�

��

��

��

��

��

��

��

��

��

��

��

��

��

��

��

��

��

��

��

��

��

��

��

��

��

��

��

��

��

��

��

OCCURRENCESONOPERATIONORORDEROUTPUT


PAGEPREV_FIELDPREV_FORMPREVIOUSPIPELINE

QUEUE

RECORDRECORD_CONSISTENCYREFREFERENCEREFRESHREJECTREPAINTREPEATREPEATEDREQUIREDRESTARTRESULTRETRIEVERETRIEVE_VALUERETURNREVERSEREVOKERIGHTROLLBACKROWROW_INDEXROW_LOWER_BOUNDSROW_ORIGINROW_UPPER_BOUNDSROW_VALUED

SCHEMASCREEN

SEARCH_RANGESSECSECONDSECONDSSELECTSELECTEDSELECTED_SET_SCROLLBARSETSET_CONSISTENCYSHLIKESLOCKSQL_COLUMN_CONDITIONSQL_OPTIONAL_CONDITIONSQL_ORDER_BY_CLAUSESQL_ORDER_BY_COLUMNSQL_WHERE_CLAUSESTARTSTOP_FOR_INPUTSTORESTOREDSTRINGSWITCH

TAB_STOPTABLETARGET_FIELDTARGET_TABLETEXTTHENTIMETIMERTOTRIMTRUETX

517Appendix A: ACCELL/SQL Reserved Words

UNCACHEDUNDEFINEDUNDERLINEUNKNOWNUNLOCKUNTILUPDATEUPDATE_ALLOWEDUPDATEABLEUSAGEUSE_BASE_WINDOWUSERMENUUSINGVALUESVIEWVOID

WAITWHENWHEREWHILEWIDTHWINDOW_HEIGHTWINDOW_WIDTHWORKWRITE

XLOCK

ZOOM

��

Appendix B: External Files

The following files, located in the release include directory, are requiredby some of the functions used in form scripts.

avalmacs.h Defines macros for the AVAL structure.

chookincl.h Defines all elements required for passing values to andfrom a function.

chooktb.c Defines external C functions.

command.h Defines return value names for user commands.

dbmserrors.h Defines the error information passed to a DBMS_ERRORfunction.

rhli.h Defines database specifications.

rhlierr.h Defines database error status values.

smcodes.h Defines the symbolic constants used with theserve_message$( ) system function.

sscodes.h Defines the values returned by the status$( ) systemfunction.

��

��

��

520 Appendix B: External Files

�

521

��

�

��

��

��

��

�� !�� !�� "��

��

�� #$�� %�� !"��#$�� !��!��

��

&�� '��!��!�� (" �� !��)��

��

��)�� (�� )��)�� "��

��

�� !�� !��!��!��!��)�� ) �� (��

��

*�) �� )��+��,-��%��(�� .�� /�� ,-�!� �� 0��1�/�� ! �� 0��1�'��$��!�2��,-�!��3&��

��

�� (�� 4 �� (��)��

��

�� !�� ! �"�� " #�" �#��

�� Glossary

��$��

��)�� 5��)�� 6� ��)��

��%��&��

��#$��"�� (��

��

�� )��)��(�� %��

��

�� (�� (��+

��"��(�

,7.%��(��8"��9

�� (�

/��!�� 4�� (��'�� )�� ,7.%��(��(��

��) �� (��+

�%&-3�� '%��7�� &��

3-%�,'� ��,'3$�.&&��3 ��:�

.'3�,2

''

7��

'�

7�� ( ��

�$��

�� ) � �� !��!�� )�� %�� 5�� "��)�� ( )*! �)*!��)+ '�

�&��

�� 4( �� ) ��(�� ) ��,7.%��;� ��(��3�'��

%��

�� 4 �� +��

�� !�� ,<��

523��

%��$��

��)�� )�� 2��)�� (�� )�� 5��)��

%��

&�� '�� !��

%��

�� )�� (�!��!� ��5��"��) �� !��

$��)�� ;��(��)�� !�"�� !��)�� !��

%��

�� #$�� )��(�� (�� (�� )��

�� "��(��#$��+

��

��

��

��

��

��

��$��

�� )�� (�� )�� 5�� (��

$��)�� ;��(��)�� !�"�� !��)�� !��

��)�� (��(��

��$��

��)�� )��0��)��1�� 0��(�1��)�� +� ��(��)��

!'(�"

,�� (��

��

��;� )��

�� !�� ,<�%��

��,

�� ;�� !�� !��!�� !�� (��

�� Glossary

��%��

�� (�� :��$��(�� (��)��#$��

��) �� "��(��+

%��

��

%��

=��

*��

��

��%��

�� #$��!�� !��)��!��)�� (�� +

��

��

��

�� (�� )�� "��.�� ;�� !�� )��

��%��%��

/ �� !�� (� �� !��"��!�&��-.�

"/�0��1��2

�� ;� �(�� 4( ��(��"�

��$��

��)�� 5��)�� ,7.%��

34' )+4 '

�� )�� (� )��)�� (�� )��>�� )��34' )+4 '�� (��4�� )�� )�� (��

$��

�� )��)�� )�� )�� 6�� )��

,��&��

��"�� " #�" �#�� "�� )�� ,-��

accell/sql: script and function reference

Documents