The ACCESS function establishes a connection between the caller and OAM. The caller supplies an eight-byte area identified by the TOKEN parameter. ACCESS stores a token into this area. The token set by ACCESS must be specified on all other OSREQ calls. A successful OSREQ ACCESS request must precede any other type of OSREQ request. The syntax diagram for the OSREQ ACCESS function follows.

Syntax for OSREQ ACCESS

>>-OSREQ ACCESS--MF=-+-L---------------------------------+------>
                     +-(M,parameter_list-+-----------+-)-+   
                     |                   '-,COMPLETE-'   |   
                     '-(E,parameter_list-+-----------+-)-'   
                                         '-,COMPLETE-'       

>--+-------------------------------------+---------------------->
   |       (1)                           |   
   '-TOKEN----=-+-token_area-----------+-'   
                '-(token_area_pointer)-'     

>--+--------------------------------------------------+--------->
   |          (2)                                     |   
   '-IADDRESS----=-+-SQL_interface_module_address---+-'   
                   '-(SQL_interface_module_pointer)-'     

>--+-------------------------------------+---------------------->
   '-MSGAREA=-+-message_area-----------+-'   
              '-(message_area_pointer)-'     

>--+------------------------------------+----------------------->
   '-RETCODE=-+-return_code-----------+-'   
              '-(return_code_pointer)-'     

>--+------------------------------------+----------------------->
   '-REACODE=-+-reason_code-----------+-'   
              '-(reason_code_pointer)-'     

>--+--------------------------------------+--------------------><
   '-TTOKEN=-+-tracking_token-----------+-'   
             '-(tracking_token_pointer)-'     

1. This keyword must be specified on at least one of the forms if the MF=E does not indicate COMPLETE.
2. This keyword indicates that a connection to DB2 already exists.

The OSREQ ACCESS function establishes the environmentally-dependent resources needed for other OSREQ function processing in the address space. In environments other than CICS or under the DSN command processor, the DB2 call attachment facility (CAF) is used to establish a connection and open thread between the application unit of work (task) and DB2. This allows for efficient database processing and synchronization of database activities by the application. An exception to this DB2 connection is when the IADDRESS parameter is specified, which is further described below.

In the CICS and DSN command processor environments, the ACCESS function assumes a connection and open thread to DB2 already exists, so CAF services are not needed.

In environments where a connection and open thread to DB2 already exist, but the ACCESS function cannot detect this condition (for example, IMS), the IADDRESS= keyword must be used to specify the structured query language (SQL) interface module entry point address. This address will be used for all SQL processing in the other OSREQ functions. See Table 1 for the effects of the IADDRESS parameter when used in various processing environments.

To limit the scope of database activities synchronized by the application, each application should issue its own ACCESS. The application must observe the DB2 restrictions regarding multiple threads from a single task as described in the IBM Information Management Software for z/OS Solutions Information Center.

When the calling program no longer requires OSREQ services, it issues the OSREQ UNACCESS request. This clears the token contents. The token cannot be used after OSREQ UNACCESS is issued.