ACCESS Function

Provides access to the current states of various data elements. Can be used only within Embedded Basic subroutines.

Syntax

ACCESS(data-element)

Syntax Elements

data-element is a number specifying the data element to be referenced.

Operation

If the ACCESS function is called from an illegal environment, it returns 0 and raises the following run time error:

[B160] Program progname.  Line number.
ACCESS(n) is not supported in this environment.
ZERO returned.

Data Elements

The following table lists the legal values for data-element and the information returned for each:

Element Returns Trigger English Other
1 A reference to the calling file. √ √ X
2 If the calling file is a data section, a reference to the dictionary of the calling file. If the calling file is a dictionary, a reference to the calling file. √ √ X
These two elements allow you to access other items in the trigger file by passing the file reference to I/O statements such as READ and WRITE.      
3 The item body. Null if a delete operation. √ √ X
4 Item count (NI). X √ X
5 Attribute count (NA). X √ X
6 Value Count (NV). X √ X
7 Subvalue Count (NS). X √ X
8 Detail Count (ND). X √ X
9 Break count (NB). X √ X
10 The id of the item. √ √ Null
11 The file name (NF). This will be in the form {DICT} {/account/}filename{,data-section-name}. √ √ Null
12 True if a PRE-DELETE or POST-DELETE trigger. √ X X
13 In triggers, always returns 0. 0 X X
16 True if the item does not exist; false otherwise. Its value therefore depends on the type of trigger. See ACCESS(16) below: √ X X
17 True if input conversion; False if output conversion. X √ √
20 In a POST-WRITE trigger, if true, indicates that the item was modified by the PRE-WRITE trigger; if false, the item was written without modification. Always false in PRE-WRITE, PRE-DELETE and POST-DELETE triggers. √ X X
23 The calling environment. 1 3 3
30 A number that identifies the calling sub-environment. See ACCESS(30) below. √ √ √
31 A string containing any unprocessed data that forms part of the current conversion code. See ACCESS(31) below. X √ √
32 A number that identifies the type of process that ran the subroutine from which the ACCESS function was called. Zero if called from English; otherwise non-zero. X √ √
Key:
The Trigger, English and Other columns list the values returned in different calling environments. The Other column covers circumstances where a dictionary subroutine is called from a conversion environment other than English (for example, from DataBasic using the ICONV or OCONV function). Use ACCESS(23) and ACCESS(32) to determine the calling environment.
The following characters have special meanings:

√ Legal in this environment.

X Illegal in this environment.

All unlisted elements are illegal.
In the Returns column, the codes NA, NV, etc. given in parentheses are the equivalent English operand system parameters.

Go to top buttonACCESS(16)

ACCESS(16) returns true if the item does not exist; false otherwise. Its value therefore depends on the type of trigger:

PRE-WRITE True if a new item is being created; false if an existing item is being updated.

PRE-DELETE Normally false, but true if the user is attempting to delete a non-existent item (if the item does not exist, no action is taken, but any triggers still run).

POST-DELETE Always true.

POST-WRITE Always false.

Note that ACCESS(16) checks whether the item exists each time it is called.

Go to top buttonACCESS(30)

For each of the different calling environments, ACCESS(30) returns a number associated with the command or reason for entry.

Environment ACCESS(23) ACCESS(30) Calling Sub-environment
Trigger 1 0 PRE WRITE trigger.
    1 POST WRITE trigger.
    2 PRE DELETE trigger.
    3 POST DELETE trigger.
    4 PRE CLEAR trigger.
    5 POST CLEAR trigger.
    6 PRE DELETE FILE trigger.
    7 POST DELETE FILE trigger.
Conversion 3 0 CALL conversion code.
    1 B conversion code.
    2 User-defined User Exit.

ACCESS(31)

ACCESS(31) returns any unprocessed data remaining after the current conversion code has been parsed. For example, the conversion code

CALL DICT1svm45

calls the DICT1 subroutine, with the string "svm45" remaining unprocessed. In this case, ACCESS(31) will return the string 45 – svm is a subvalue mark that acts as a separator between the subroutine name and the following data.

Go to top buttonExamples

* Named Common - used to share info between Pre and Post Triggers
 COMMON /TRIGSTUFF/ T.TYPE

* Determine type of operation
 DELETING = ACCESS(12)  ;* True if item being deleted
 NEW.ITEM = ACCESS(16)  ;* True if new item being written
 BEGIN CASE
    CASE DELETING; T.TYPE="DEL";    * delete item
    CASE NEW.ITEM; T.TYPE="NEW";    * write new item
    CASE 1;        T.TYPE="UPD";    * update existing item
 END CASE

This example calls ACCESS(12) and ACCESS(16) to determine whether an item is being created, updated or deleted, and stores the result in a named common area for use in a subsequent trigger.

* Construct Log record
 LOGID = DATE():'~':TIME()
 LOGITEM = ''
 LOGITEM<1> = ACCESS(10)  ;* Item-id of item written or deleted
 LOGITEM<2> = T.TYPE      ;* Operation type (NEW, UPD or DEL)
 *
 * Record operation to logfile
 *
 WRITE LOGITEM ON LOGFILE,LOGID ON ERROR
   *
   * Write to logfile failed, but operation on datafile completed.
   * Not much we can do here except shout loudly.
   * If using Transaction Boundaries we could use TRANSABORT.
   *
   CRT
   CRT "*** ERROR - Cannot write to logfile"
   CRT
 END

This example calls ACCESS(10) to obtain the item-id of the item being written or deleted and then writes this information to a log file.

Go to top button