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 an integer 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	√	√
34	A string containing the next conversion code. If the current conversion code is the last one, an empty string is returned.	X	√	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.

ACCESS(16)

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

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

PRE-DELETENormally 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-DELETEAlways true.

POST-WRITEAlways false.

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

ACCESS(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 READ trigger
		5	POST READ trigger
		6	PRE CLEAR FILE trigger.
		7	POST CLEAR FILE trigger.
		8	PRE DELETE FILE trigger.
		9	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.

ACCESS(34)

Where an Embedded Basic subroutine is used in a conversion code sequence, the ACCESS(34) function returns the next conversion code. For example, the following:

CALL DICT1vmMCU

calls the DICT1 subroutine and its result is passed to the MCU conversion code (convert to upper case). If DICT1 calls ACCESS(34), this will return "MCU" - vm is the value mark that separates the conversion codes.

ACCESS(34) can be useful when writing Embedded Basic subroutine to replace user exits migrated from some other MultiValue systems. If a user exit parameter is separated from the user exit call by a value mark, use ACCESS(34) to fetch it, rather than ACCESS(31). For example, in:

U5555vm45

if user exit 5555 is replaced with an Embedded Basic subroutine, this would have to call ACCESS(34) to fetch the parameter "45". Note that before returning, the subroutine should use the ACCESS(34) statement to delete this parameter to prevent it being processed as a normal conversion code.

Examples

* 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.